SF Symbols & Iconography API Reference

Lifecycle Position

autonomous-ui-workflow

Quick Reference

Image(systemName:)

Image(systemName:variableValue:)

.symbolRenderingMode(_:)

.symbolVariant(_:)

.symbolEffect(_:)

.foregroundStyle(_:_:)

Rendering Modes

.monochrome

.symbolRenderingMode(.monochrome).foregroundStyle(.purple)

.hierarchical

.symbolRenderingMode(.hierarchical).foregroundStyle(.purple)

.multicolor

.symbolRenderingMode(.multicolor)

.palette

.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

Image(systemName: "star.fill")

Label("Favorites", systemImage: "star.fill")

.fontWeight(.semibold)

.symbolEffect(.bounce, value: trigger)

Image(systemName: "wifi", variableValue: 0.5)

.symbolRenderingMode(.multicolor)

.symbolRenderingMode(.palette)

foregroundStyle(.red, .blue)

Common Mistakes

1. Image(systemName:)

   without

   Label

   in buttons — no accessibility text for VoiceOver
2. Mismatched symbol weight with adjacent text — icons look too thin/thick next to text. Match with

   .fontWeight()

   or

   .imageScale()

3. Using

   .resizable().frame()

   for sizing instead of

   .font()

   — breaks alignment with text. Use

   .font(.title)

   to match text size
4. Missing

   .symbolRenderingMode()

   — defaults to monochrome which may not match design intent
5. Hardcoded symbol names without checking SF Symbols availability — some symbols require iOS 16+ or 17+

Button(action: addFavorite) {
    Image(systemName: "star.fill")  // no label — VoiceOver reads nothing useful
}

Button(action: addFavorite) {
    Label("Add to Favorites", systemImage: "star.fill")
}

Image(systemName: "heart.fill")
    .resizable()
    .frame(width: 24, height: 24)  // disrupts text baseline alignment

Image(systemName: "heart.fill")
    .font(.title2)  // scales with Dynamic Type and aligns with text

Checklist

• Buttons and toolbar items use

  Label("text", systemImage:)

  not bare

  Image

• 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 tinting

• swiftui-ui-patterns

  — review checklist includes accessibility label checks

• macos-app-design

  — macOS toolbar icon conventions