SwiftUI Component Library

Generate production-ready SwiftUI components with proper architecture, accessibility, and state management. Accelerate UI development with pre-built, customizable components perfect for financial apps, forms, and data-driven interfaces.

Quick Start

Generate a Component

python scripts/generate_component.py <type> <ComponentName> <output_path>

Available component types:

• button - Action buttons with multiple styles
• text_field - Text input with validation
• currency_field - Currency input with formatting
• percentage_field - Percentage input with slider
• loading_view - Loading states (spinner/progress/inline)
• empty_state - Empty data placeholders
• form_section - Grouped form inputs

Example:

# Generate currency field for mortgage calculator
python scripts/generate_component.py currency_field LoanAmountField ./Sources

# Generate percentage field for interest rate
python scripts/generate_component.py percentage_field InterestRateField ./Sources

# Generate button component
python scripts/generate_component.py button PrimaryButton ./Sources

Generate a Design System

python scripts/generate_design_system.py <output_path> [ProjectName]

Creates a complete design system with:

• Color palette (primary, secondary, semantic colors)
• Typography scale (display, headline, title, body, label)
• Spacing constants (xxsmall to xxlarge)
• Corner radius values
• Shadow styles
• Button styles (primary, secondary, tertiary)
• Text field styles
• Card modifiers

Example:

python scripts/generate_design_system.py ./Sources
python scripts/generate_design_system.py ./Sources MortgageApp

Component Features

Every generated component includes:

✅ Accessibility Built-In

• VoiceOver labels and hints
• Dynamic Type support
• Accessibility values
• Semantic traits

✅ State Management

• Proper @State, @Binding, @FocusState usage
• SwiftUI best practices
• Clean data flow

✅ Preview Providers

• Multiple state examples
• Edge case coverage
• Interactive previews

✅ Production-Ready

• Error handling
• Input validation (where applicable)
• Consistent styling
• Documentation comments

Workflow

Step 1: Generate Design System (First Time)

# Create your design system foundation
python scripts/generate_design_system.py ./YourApp/Sources

This creates DesignSystem.swift with:

• Colors that adapt to light/dark mode
• Typography scales
• Spacing and layout constants
• Reusable button and text field styles
• Card and shadow styles

Step 2: Generate Components as Needed

# For mortgage calculator
python scripts/generate_component.py currency_field LoanAmountInput ./Sources
python scripts/generate_component.py percentage_field InterestRateInput ./Sources
python scripts/generate_component.py button CalculateButton ./Sources

# For forms
python scripts/generate_component.py text_field EmailField ./Sources
python scripts/generate_component.py form_section FormGroup ./Sources

# For loading states
python scripts/generate_component.py loading_view LoadingSpinner ./Sources
python scripts/generate_component.py empty_state NoDataView ./Sources

Step 3: Customize Components

All generated components are fully editable templates. Customize:

• Colors using your design system
• Validation rules
• Styling and layout
• Behavior

Step 4: Compose into Views

Combine components to build complex UIs:

struct MortgageCalculator: View {
    @State private var loanAmount: Decimal = 250000
    @State private var rate: Double = 6.5
    
    var body: some View {
        Form {
            FormSection("Loan Details") {
                LoanAmountInput(amount: $loanAmount)
                InterestRateInput(percentage: $rate)
            }
            
            CalculateButton("Calculate", style: .primary) {
                calculate()
            }
        }
    }
}

Reference Documentation

For Component Patterns and Best Practices

Read references/component-patterns.md when you need:

• State management patterns (@State, @Binding, @FocusState)
• Form component examples
• Validation patterns
• Accessibility guidelines
• Testing strategies
• Best practices for composition

When to read: Before building complex forms, implementing validation, or setting up state management.

For Mortgage Calculator Specific Guidance

Read references/mortgage-calculator-guide.md when you need:

• Complete mortgage calculator examples
• Loan input components
• Payment display components
• Amortization schedule views
• Comparison tools
• Affordability calculators

When to read: Building any financial calculator or mortgage-related UI.

Component Library Structure

Buttons (button)

Purpose: User actions and navigation

Styles:

• .primary - Main call-to-action (blue background)
• .secondary - Secondary actions (gray background)
• .tertiary - Text-only buttons (no background)
• .destructive - Delete/remove actions (red background)

Features:

• Press animation
• Accessibility labels and hints
• Consistent padding and sizing

Text Fields (text_field)

Purpose: Text input with validation

Validation rules:

• .required - Cannot be empty
• .email - Valid email format
• .minLength(n) - Minimum character count
• .maxLength(n) - Maximum character count
• .custom((String) -> String?) - Custom validation

Features:

• Real-time validation
• Error messages
• Focus state management
• Accessibility support

Currency Fields (currency_field)

Purpose: Currency input with proper formatting

Features:

• Automatic currency symbol
• Decimal precision (2 places)
• Locale-aware formatting
• Keyboard type: decimal pad
• Accessibility value with full currency

Perfect for:

• Loan amounts
• Down payments
• Monthly payments
• Any monetary value

Percentage Fields (percentage_field)

Purpose: Percentage input with slider and text field

Features:

• Combined slider + text input
• Configurable decimal places (0-3)
• Range limiting
• Real-time updates
• Accessibility labels

Perfect for:

• Interest rates
• Down payment percentages
• Tax rates
• Any percentage value

Loading Views (loading_view)

Purpose: Indicate loading states

Styles:

• .spinner - Full-screen spinner with message
• .progress(Double) - Progress bar with percentage
• .inline - Compact inline loading indicator

Features:

• Customizable messages
• Progress tracking
• Accessibility announcements

Empty States (empty_state)

Purpose: Show when no data exists

Features:

• SF Symbol icon
• Title and message
• Optional action button
• Centered layout
• Accessibility support

Use cases:

• No calculations yet
• Empty search results
• No saved items

Form Sections (form_section)

Purpose: Group related form inputs

Features:

• Header title
• Optional footer text
• Rounded background
• Consistent spacing
• Accessibility header trait

Perfect for:

• Grouping loan details
• Separating input sections
• Organizing complex forms

Integration with Existing Skills

Works With iOS Build CI/CD (Skill #6)

Components are validated in CI:

• SwiftUI syntax checking
• Compilation verification
• Preview generation
• Accessibility validation

Works With Code Quality Auditor (Skill #2)

Components follow best practices:

• No force unwrapping
• Proper optional handling
• @MainActor compliance
• State management patterns

Works With Architecture Review (Skill #3)

Components demonstrate:

• Proper view decomposition
• State management
• Separation of concerns
• MVVM patterns

Works With Testing Suite (Skill #4)

Components are testable:

• Preview providers for manual testing
• ViewInspector compatibility
• Snapshot testing ready
• Unit test examples in references

Tips for Success

1. Start with Design System

Always generate the design system first. It provides:

• Consistent colors across the app
• Typography scales
• Spacing constants
• Reusable styles

2. Generate, Then Customize

Don't write components from scratch:

1. Generate base component
2. Customize for your needs
3. Update colors to use design system
4. Add project-specific logic

3. Use Form Sections

Group related inputs in form sections:

FormSection("Loan Details") {
    // Multiple related inputs
}

FormSection("Terms", footer: "Helpful context") {
    // More inputs
}

4. Validate Early

Use built-in validation on text fields:

ValidatedTextField("Email", text: $email, validation: .email)
ValidatedTextField("Name", text: $name, validation: .required)

5. Compose Components

Build complex UIs from simple components:

// Complex calculator view
struct Calculator: View {
    var body: some View {
        Form {
            LoanInputSection()      // Multiple currency fields
            TermSection()            // Percentage + picker
            ResultsSection()         // Custom display
            ActionSection()          // Button
        }
    }
}

6. Read References

Before building complex features:

• Building forms? → Read component-patterns.md
• Mortgage calculator? → Read mortgage-calculator-guide.md
• Need examples? → Both files have complete working code

Common Use Cases

Mortgage Calculator

# Generate all needed components
python scripts/generate_design_system.py ./Sources MortgageApp
python scripts/generate_component.py currency_field LoanAmountField ./Sources
python scripts/generate_component.py currency_field DownPaymentField ./Sources
python scripts/generate_component.py percentage_field InterestRateField ./Sources
python scripts/generate_component.py button CalculateButton ./Sources
python scripts/generate_component.py form_section FormGroup ./Sources
python scripts/generate_component.py empty_state EmptyCalculation ./Sources

# Then read the mortgage calculator guide
# references/mortgage-calculator-guide.md has complete examples

User Registration Form

# Generate form components
python scripts/generate_design_system.py ./Sources
python scripts/generate_component.py text_field EmailField ./Sources
python scripts/generate_component.py text_field PasswordField ./Sources
python scripts/generate_component.py button SubmitButton ./Sources
python scripts/generate_component.py form_section Section ./Sources
python scripts/generate_component.py loading_view LoadingView ./Sources

# Read validation patterns
# references/component-patterns.md section on validation

Data Dashboard

# Generate display components
python scripts/generate_design_system.py ./Sources
python scripts/generate_component.py loading_view DataLoader ./Sources
python scripts/generate_component.py empty_state NoData ./Sources
python scripts/generate_component.py form_section StatCard ./Sources

Best Practices

1. Follow SwiftUI Conventions

• Use @State for local state
• Use @Binding for parent-child communication
• Use @FocusState for keyboard management
• Avoid @ObservedObject in reusable components

2. Keep Components Focused

Each component should:

• Have single responsibility
• Be reusable across features
• Not depend on specific models
• Accept generic bindings

3. Prioritize Accessibility

Every component should:

• Have descriptive labels
• Announce value changes
• Support Dynamic Type
• Work with VoiceOver

4. Test Components

Test components with:

• Preview providers (multiple states)
• Unit tests (ViewInspector)
• UI tests (accessibility)
• Manual testing (real devices)

5. Document Customizations

When customizing components:

• Add comments explaining changes
• Document expected behavior
• Note any deviations from templates
• Update preview providers

Next Steps

After generating components:

1. Integrate with your app - Add components to your project
2. Customize styling - Update colors to match design system
3. Add business logic - Implement calculation functions
4. Test thoroughly - Use preview providers and real devices
5. Build features - Compose components into complete views

For complete examples and patterns, read the reference documentation:

• references/component-patterns.md - General patterns
• references/mortgage-calculator-guide.md - Financial apps

---

You now have the tools to build production-ready SwiftUI UIs 50% faster!