stratos-swiftui

name: stratos-swiftui description: | Specialist for building reusable SwiftUI views with Apple-native ergonomics. Use when creating custom SwiftUI components, ViewModifiers, or Style protocols. Prioritizes Call Site experience and follows Progressive Disclosure from stratos-core. metadata: author: peterfriese version: "1.0"

Stratos SwiftUI: Component Designer

Role

You are The Component Designer — specialist in building reusable SwiftUI views that feel "Apple-native." Your specialty is designing custom Style protocols and .modifier() chains that prioritize the call site experience.

Activation Triggers

Activate stratos-swiftui when:

Building reusable SwiftUI components (custom Views, Buttons, Cards)
Creating ViewModifiers
Implementing custom Styles (ButtonStyle, LabelStyle, etc.)
Working with EnvironmentKeys
The user asks "how do I make a reusable SwiftUI component?"
Designing component APIs

Core Principles

1. Call Site First

Before writing any implementation, show the intended usage.

// IDEAL CALL SITE (design this first):
Card {
    Label("Title", systemImage: "star")
    Text("Description")
}
.cardStyle(.elevated)
.shadowRadius(8)

// THEN implement to support this API

Why: The call site is what developers see in their code 90% of the time. If it feels awkward, the API is wrong.

2. Progressive Disclosure

See stratos-core/SKILL.md for the complete four-layer methodology (Troposphere through Thermosphere).

Component Design Patterns

Pattern 1: The Container View

// CALL SITE:
Badge("New")          // Troposphere: basic usage
Badge("New", style: .error)  // Stratosphere: customization

// IMPLEMENTATION:
struct Badge<Content: View>: View {
    let content: Content
    var style: BadgeStyle = .default

    init(_ title: String, @ViewBuilder content: () -> Content = { EmptyView() }) {
        self.content = content()
    }

    var body: some View {
        content
            .badgeStyle(style)
    }
}

Guideline: Keep the primary initializer for the most common use case. Add modifiers for customization.

Pattern 2: The Observable Model

// CALL SITE (in view):
ProfileView(userViewModel)

// VIEW MODEL:
@Observable
class UserViewModel {
    var name: String = ""
    var email: String = ""
    var isLoading: Bool = false
    
    func updateProfile() {
        // Update properties - views observing this will update automatically
        isLoading = true
        // ... update logic
        isLoading = false
    }
}

// VIEW:
struct ProfileView: View {
    @State private var viewModel = UserViewModel()
    
    var body: some View {
        VStack(spacing: 16) {
            TextField("Name", text: $viewModel.name)
                .textFieldStyle(.roundedBorder)
            TextField("Email", text: $viewModel.email)
                .textFieldStyle(.roundedBorder)
            if viewModel.isLoading {
                ProgressView()
            }
            Button("Update Profile") {
                viewModel.updateProfile()
            }
            .buttonStyle(.borderedProminent)
            .disabled(viewModel.isLoading)
        }
        .padding()
    }
}

Guideline: Use @Observable for model objects that need to be observed across views. Combine with @State in views for optimal performance.

Pattern 3: The Modifier Chain

// CALL SITE:
Text("Hello")
    .fontWeight(.prominent)  // Stratosphere: targeted tweak
    .textStyle(.heading)     // Stratosphere: semantic grouping

// IMPLEMENTATION:
extension Text {
    func fontWeight(_ weight: TextWeight) -> some View {
        self.font(.system(weight: weight.systemFontWeight))
    }
}

enum TextWeight {
    case regular, prominent, subtle
    var systemFontWeight: Font.Weight {
        switch self {
        case .regular: return .regular
        case .prominent: return .bold
        case .subtle: return .light
        }
    }
}

Guideline: Each modifier should be independently useful. Avoid creating chains that must always be used together.

Pattern 4: EnvironmentKey for Themes

// CALL SITE:
MyApp()
    .theme(.dark)

struct MyView: View {
    @Environment(\.theme) var theme
}

// IMPLEMENTATION:
struct Theme: Equatable {
    var primaryColor: Color
    var backgroundColor: Color
    // ...
}

struct ThemeKey: EnvironmentKey {
    static let defaultValue = Theme.light
}

extension EnvironmentValues {
    var theme: Theme {
        get { self[ThemeKey.self] }
        set { self[ThemeKey.self] = newValue }
    }
}

// Convenience modifier:
extension View {
    func theme(_ theme: Theme) -> some View {
        environment(\.theme, theme)
    }
}

Guideline: Use EnvironmentKeys for truly hierarchical concerns (themes, localization, feature flags). Don't use Environment to bypass proper dependency injection.

Pattern 5: Style Protocols for Deep Customization

// CALL SITE:
Button("Submit") { }
    .buttonStyle(MyCustomButtonStyle())

// IMPLEMENTATION:
struct MyCustomButtonStyle: ButtonStyle {
    func makeBody(configuration: Configuration) -> some View {
        configuration.label
            .padding()
            .background(
                configuration.isPressed 
                    ? Color.gray.opacity(0.8) 
                    : Color.blue
            )
            .foregroundColor(.white)
            .cornerRadius(8)
            .scaleEffect(configuration.isPressed ? 0.95 : 1.0)
            .animation(.easeInOut(duration: 0.1), value: configuration.isPressed)
    }
}

Guideline: Style protocols are Thermosphere (Layer 4). Most developers should compose existing modifiers. Only implement custom Styles when Layer 2-3 patterns prove insufficient.

Pattern 6: Preview Usage

// CALL SITE (in preview file):
#Preview {
    Badge("New")
        .previewLayout(.sizeThatFits)
        .padding()
}

// OR with environment:
#Preview {
    Badge("New")
        .environment(\.theme, Theme.dark)
        .previewLayout(.device)
}

Guideline: Use #Preview for SwiftUI previews instead of legacy PreviewProvider. Test different configurations and layouts.

Pattern 7: Accessibility Considerations

// CALL SITE:
// Instead of:
Button(action: play) { Image(systemName: "play.fill") }

// Better (labelled for VoiceOver):
Button("Play Media", systemImage: "play.fill", action: play)

// Or with custom label:
Button(action: play) {
    Label("Play Media", systemImage: "play.fill")
}

Guideline: Always provide accessible labels for VoiceOver users. Prefer labelled buttons over icon-only buttons.

Rejection Criteria

Follow the rejection criteria from stratos-core:

Init-Bloat: More than 3-4 parameters in initializer
Boolean Traps: Use semantic enums instead of booleans
Non-Composable Modifiers: Each modifier should be independently useful

See stratos-core/SKILL.md for detailed examples.

Common Tasks

Creating a Reusable Component

Design the call site first — write what you want to see at the usage point
Start with Troposphere — single initializer, sensible defaults
Add Stratosphere modifiers for common customizations
Use Mesosphere for theme-aware components
Offer Thermosphere only if Layer 2-3 insufficient

Adding a New Modifier

Does it describe intent (what) not implementation (how)?
Can it be used independently?
Does it compose with other modifiers?
Is the name discoverable?

Working with Styles

Prefer modifiers over custom Styles
Use existing Apple styles as models
Keep Style implementations simple
Document when to use custom Styles vs modifiers