Customization Recipes

For complete customization guide with LLM prompts, see Building Your App

Shipping a white-labeled version? Customizing colors and onboarding isn’t enough on its own. Before you submit, run the App Store 4.3 hardening checklist to clear binary fingerprints, branding leftovers, and listing copy that still reads like a template.

Branding

Change App Colors

What to customize: The design tokens read their colors from the DesignSystem package’s own asset catalog via Bundle.module:

Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets/
├── AccentPrimary.colorset      # DSColors.accentPrimary / .primary
├── AccentSecondary.colorset
├── Background.colorset
├── Surface.colorset
├── SurfaceElevated.colorset
├── TextPrimary.colorset
├── TextSecondary.colorset
├── ChipBackground.colorset
├── Danger.colorset / Success.colorset / Warning.colorset
└── ...

Steps:

Open the color set in Xcode
Change Light Appearance color
Change Dark Appearance color
Build → colors update everywhere

All components use design tokens - change once, applies everywhere. Note: the system/light/dark themes read these assets, while the aurora and obsidian themes use hard-coded values in DSColors.swift, so customizing those requires editing the matching switch activeTheme branches.

Replace App Icon

Steps:

Create 1024×1024 PNG
Drag to SwiftAIBoilerplatePro/Assets.xcassets/AppIcon.appiconset
Xcode generates all required sizes
Build and verify

Customize Onboarding

File: SwiftAIBoilerplatePro/AppShell/OnboardingPage.swift Change the defaultPages array:

static let defaultPages: [OnboardingPage] = [
    OnboardingPage(
        title: "Your Title",
        description: "Your description",
        systemImage: "sparkles",  // Any SF Symbol
        accentColor: "blue"        // Hex or system color name
    ),
    // Add more pages...
]

UI Customization

Add Home Screen Feature Card

File: SwiftAIBoilerplatePro/AppShell/HomeContent.swift Add to HomeContent.FeatureItem.defaults (or pass your own featuredItems into HomeContent):

public static let defaults: [HomeContent.FeatureItem] = [
    // ... existing cards
    HomeContent.FeatureItem(
        title: "Your Feature",
        description: "Feature description",
        systemImage: "bookmark.fill",
        accentColor: "blue"
    ),
]

Change Chat Bubble Colors

Bubble colors are derived from design tokens, not from dedicated bubble color sets. In DSColors.swift:

bubbleUserOrFallback → accentPrimary (the AccentPrimary.colorset for system/light/dark)
bubbleAssistantOrFallback → surface (a system color, Color(.secondarySystemBackground), for system/light/dark)

Change the user bubble by editing AccentPrimary.colorset in Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets/. The assistant bubble follows the system surface color, so adjust the surface token’s switch activeTheme branch in DSColors.swift to override it.

Add Custom Theme

Create Color Sets

In the DesignSystem package catalog (Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets), create color sets for any semantic colors your theme needs.

Add Theme Case

In SettingsDTO.swift, add a case to the string-backed Theme enum (used by the settings UI):

public enum Theme: String, Sendable, Equatable, CaseIterable {
    case system, light, dark, aurora, obsidian
    case myTheme  // Add this
}

Map Colors

In DSColors.swift, add a case .myTheme to the internal ThemePalette enum and to each token switch activeTheme block.

Add to Picker

The appearance picker in SettingsAppearanceSection.swift iterates SettingsDTO.Theme.allCases, so the new case appears automatically once the enum and mappings are in place.

Feature Customization

Add Custom AI Persona

File: Packages/FeatureChat/Sources/FeatureChat/ViewModels/ChatViewModel.swift LLMMessage lives in FeatureChat and its role is a String ("user" | "assistant" | "system"):

// Inside ChatViewModel.send() (the real entry point is `public func send() async`),
// build the prompt list with a persona system message:
let systemPrompt = LLMMessage(
    role: "system",
    content: """
    You are a professional Swift developer.
    Provide clear, concise answers with code examples.
    """
)

let messages = [systemPrompt] + history  // `history` mapped to [LLMMessage]
// Pass `messages` to llmClient when streaming

The server-side AI Edge Function (supabase/functions/ai/index.ts) injects its own fixed SYSTEM_PROMPT and clients may only send user/assistant roles, so a client-supplied system message is for local/echo flows. To change the deployed persona, edit SYSTEM_PROMPT in the function and redeploy.

Add New SwiftData Model

Create Model

@Model
class YourModel {
    @Attribute(.unique) var id: UUID
    var property: String
    var createdAt: Date
}

Create DTO

struct YourModelDTO: Identifiable, Sendable {
    let id: UUID
    let property: String
    
    init(_ model: YourModel) {
        self.id = model.id
        self.property = model.property
    }
}

Create Repository

Protocol + implementation following existing patterns

Add to Schema

In SwiftAIBoilerplatePro/Composition/CompositionRoot.swift, add your model to the Schema([Conversation.self, Message.self, Settings.self]) array.

Add Custom Setting

Update Settings Model

In Packages/Storage/Sources/Storage/Models/Settings.swift:

@Model
public final class Settings {
    public var theme: String  // "system" | "light" | "dark"
    public var yourSetting: Bool = false  // Add this
}

Update ViewModel

@Observable
class SettingsViewModel {
    var yourSetting: Bool
    
    func toggleYourSetting(_ enabled: Bool) async {
        // Save to repository
    }
}

Update UI

Toggle("Your Setting", isOn: $viewModel.yourSetting)
    .onChange(of: viewModel.yourSetting) {
        Task { await viewModel.toggleYourSetting($0) }
    }

Backend Customization

Change AI Model

File: supabase/functions/ai/index.ts For cost safety, the function validates the requested model against an allowlist (security rule BL-003). To allow a different OpenRouter model, add it to ALLOWED_MODELS:

// Only allow-listed models are accepted; everything else is rejected with 400.
const ALLOWED_MODELS = [
  'openai/gpt-3.5-turbo',
  'openai/gpt-4o-mini',
  'anthropic/claude-3-5-sonnet',  // Add the models you want to permit
]

The request body’s model defaults to openai/gpt-3.5-turbo and must be in this list. The server-side SYSTEM_PROMPT and role allowlist (user/assistant) are also enforced here. Deploy:

supabase functions deploy ai

Add Usage Limits

PaymentsClient.currentState() and state.isSubscribed are real APIs; the per-day count below is illustrative — back it with your own repository query.

func canSendMessage() async -> Bool {
    let state = await paymentsClient.currentState()
    
    if state.isSubscribed {
        return true  // Unlimited for pro
    } else {
        let count = await messageRepository.todayCount()  // your own query
        return count < 20  // Free tier limit
    }
}

Module Customization

Each module has detailed customization examples:

Core

Custom errors, log categories

Networking

Custom requests, interceptors

Storage

New models, repositories

Auth

Social providers, custom fields

Payments

New tiers, usage limits

AI

Models, personas, prompts

FeatureChat

UI styles, actions, search

FeatureSettings

New settings, paywall

DesignSystem

Themes, components, tokens

Pro Tips

Test after each change - Don’t stack multiple changes without testing

Use design tokens - Never hardcode colors or spacing

Follow existing patterns - Look for similar features first

Keep files ≤ 300 lines - Extract components when needed

Need More Help?

Building Guide

Step-by-step guide with LLM prompts

Module Docs

Detailed technical docs

CLAUDE.md

AI coding guidelines

Architecture

System design

Getting Started

Setup Guides

Core Modules

Feature Modules

Migration

Reference

Before You Submit

Branding

Change App Colors

Replace App Icon

Customize Onboarding

UI Customization

Add Home Screen Feature Card

Change Chat Bubble Colors

Add Custom Theme

Feature Customization

Add Custom AI Persona

Add New SwiftData Model

Add Custom Setting

Backend Customization

Change AI Model

Add Usage Limits

Module Customization

Core

Networking

Storage

Auth

Payments

AI

FeatureChat

FeatureSettings

DesignSystem

Pro Tips

Need More Help?

Building Guide

Module Docs

CLAUDE.md

Architecture

​Branding

​Change App Colors

​Replace App Icon

​Customize Onboarding

​UI Customization

​Add Home Screen Feature Card

​Change Chat Bubble Colors

​Add Custom Theme

​Feature Customization

​Add Custom AI Persona

​Add New SwiftData Model

​Add Custom Setting

​Backend Customization

​Change AI Model

​Add Usage Limits

​Module Customization

Core

Networking

Storage

Auth

Payments

AI

FeatureChat

FeatureSettings

DesignSystem

​Pro Tips

​Need More Help?

Building Guide

Module Docs

CLAUDE.md

Architecture

Branding

Change App Colors

Replace App Icon

Customize Onboarding

UI Customization

Add Home Screen Feature Card

Change Chat Bubble Colors

Add Custom Theme

Feature Customization

Add Custom AI Persona

Add New SwiftData Model

Add Custom Setting

Backend Customization

Change AI Model

Add Usage Limits

Module Customization

Pro Tips

Need More Help?