Colors & ShapeStyle API Reference

Lifecycle Position

Phase 3 API Reference — load during implementation when working with colors, gradients, or tints. Dispatched from autonomous-ui-workflow Phase 2 research table.

Foreground Styling

.foregroundStyle(.teal) // single .foregroundStyle(.blue, .gray) // primary + secondary .foregroundStyle(.blue, .gray, .gray.opacity(0.5)) // + tertiary

Hierarchical: .primary , .secondary , .tertiary , .quaternary

System Colors

.black , .blue , .brown , .clear , .cyan , .gray , .green , .indigo , .mint , .orange , .pink , .purple , .red , .teal , .white , .yellow

Tint

Button("Answer") { }.tint(.green) Gauge(value: 75, in: 0...100) { }.tint(Gradient(colors: [.blue, .red]))

Background

.background(.regularMaterial) .backgroundStyle(.blue.gradient) Image(systemName: "swift").padding().background(in: Circle()).backgroundStyle(.blue.gradient)

Gradients

.linearGradient(colors: [.yellow, .blue], startPoint: .top, endPoint: .bottom) .radialGradient(Gradient(colors: [.yellow, .red]), center: .topLeading, startRadius: 15, endRadius: 80) Color.blue.gradient // standard gradient from color

Color Modifiers

Color.blue.opacity(0.5) Color.red.mix(with: .blue, by: 0.5)

Custom ShapeStyle

struct MyStyle: ShapeStyle { func resolve(in environment: EnvironmentValues) -> some ShapeStyle { environment.colorScheme == .light ? Color.red.blendMode(.lighten) : Color.red.blendMode(.darken) } }

When to Use Which

Need Use

Text, icons that adapt to dark mode foregroundStyle(.primary) , .secondary , .tertiary

Brand colors shared across views Asset catalog Color("BrandRed")

Tinting interactive elements .tint(.accentColor)

Multi-color text/icon styling foregroundStyle(.red, .blue, .green) (primary, secondary, tertiary)

Gradient backgrounds LinearGradient , RadialGradient , AngularGradient , or .gradient suffix

Platform-bridged colors Color(nsColor:) for macOS, Color(uiColor:) for iOS

Dynamic color based on scheme @Environment(.colorScheme) with conditional

Common Mistakes

• Using Color.black /Color.white instead of .primary /semantic colors — breaks in dark mode

• Hardcoding hex colors instead of asset catalog — no dark mode variant, no accessibility

• Using foregroundColor() instead of foregroundStyle() — deprecated API

• Applying .tint() and .foregroundStyle() together — tint overrides foregroundStyle on controls

• Missing .opacity() consideration — semantic colors already have built-in opacity levels

Before (incorrect):

Text("Hello") .foregroundColor(.black) // deprecated, breaks dark mode

After (correct):

Text("Hello") .foregroundStyle(.primary) // adapts to dark mode automatically

Before (incorrect):

Color(hex: "#FF3B30") // hardcoded, no dark mode variant

After (correct):

Color("BrandRed") // defined in asset catalog with Light/Dark variants

Checklist

• No hardcoded Color.black /Color.white for text or backgrounds

• Using foregroundStyle() not foregroundColor()

• Brand colors defined in asset catalog with dark mode variants

• Gradient direction matches reading direction (leading → trailing)

• Color contrast meets WCAG AA (4.5:1 for normal text, 3:1 for large text)

Cross-References

• swiftui-effects-api — blur, shadow, opacity effects that interact with colors

• swiftui-material-api — material backgrounds that adapt to underlying colors

• swiftui-ui-patterns — modern API checklist includes foregroundStyle() migration