components

Component Patterns

FULL-WIDTH CONTAINERS — REQUIRED:

• All cards, insight boxes, and content containers MUST use .frame(maxWidth: .infinity) to fill their parent
• VStack with .alignment: .leading still needs .frame(maxWidth: .infinity, alignment: .leading) for full width
• Never let a card or container shrink to fit its content — it must stretch to the parent width
• Use real asset images (from Assets.xcassets) when available — never use generic SF Symbols for content that has a custom asset (e.g., use head location images, severity faces, etc.)

BUTTON HIERARCHY (one primary per screen/section):

Level	Style	Use Case	Code
Primary	.borderedProminent	Main action (Save, Submit, Start)	.buttonStyle(.borderedProminent).controlSize(.large)
Secondary	.bordered	Alternative action (Cancel, Edit)	.buttonStyle(.bordered)
Tertiary	.borderless	Low-emphasis (Skip, Learn More)	.buttonStyle(.borderless)
Destructive	.borderedProminent	Delete, Remove	.buttonStyle(.borderedProminent).tint(.red)

• ONE .borderedProminent per screen/section — multiple primaries confuse the user.
• Full-width primary: .controlSize(.large).frame(maxWidth: .infinity).
• ALWAYS use Button() — never .onTapGesture for actions.
• Disabled buttons: .disabled(condition) — SwiftUI auto-handles opacity.

CARD DESIGN PATTERN:

VStack(alignment: .leading, spacing: AppTheme.Spacing.xSmall) {
    HStack {
        Image(systemName: "icon.name")
            .font(AppTheme.Fonts.title3)
            .foregroundStyle(AppTheme.Colors.primary)
        Spacer()
        Text("metadata")
            .font(AppTheme.Fonts.caption)
            .foregroundStyle(.secondary)
    }
    Text("Title")
        .font(AppTheme.Fonts.headline)
    Text("Description text goes here")
        .font(AppTheme.Fonts.subheadline)
        .foregroundStyle(.secondary)
}
.padding(AppTheme.Spacing.medium)
.background(AppTheme.Colors.surface)
.clipShape(RoundedRectangle(cornerRadius: AppTheme.Style.cornerRadius))
.shadow(color: .black.opacity(0.06), radius: 8, y: 4)

INPUT FIELD STATES:

• Normal: TextField with .textFieldStyle(.roundedBorder).
• Focused: @FocusState with visual highlight (border color change or underline).
• Error: red border + error message below field.

TextField("Email", text: $email)
    .textFieldStyle(.roundedBorder)
    .overlay(
        RoundedRectangle(cornerRadius: 8)
            .stroke(emailError != nil ? .red : .clear, lineWidth: 1)
    )
if let error = emailError {
    Text(error)
        .font(AppTheme.Fonts.caption)
        .foregroundStyle(AppTheme.Colors.error)
}

• Disabled: .disabled(true) — auto grays out.
• Form grouping: use Form or GroupBox for related fields.

LOADING STATES:

Pattern	Use Case	Code
Inline spinner	Button action, single item	ProgressView().controlSize(.small)
Full-screen	Initial data load	ProgressView("Loading...")
Pull-to-refresh	List refresh	.refreshable { await refresh() }
Skeleton	Content placeholder	.redacted(reason: .placeholder)
Overlay	Blocking operation	.overlay { if loading { ProgressView() } }

• Disable the triggering button while loading to prevent double-taps.
• Show loading for operations > 300ms. Instant operations need no indicator.

BADGE/CHIP PATTERN:

Text("Label")
    .font(AppTheme.Fonts.caption)
    .fontWeight(.medium)
    .padding(.horizontal, 8)
    .padding(.vertical, 4)
    .background(AppTheme.Colors.primary.opacity(0.15))
    .foregroundStyle(AppTheme.Colors.primary)
    .clipShape(Capsule())