Design System Module - SwiftAI Boilerplate Pro

Full technical details in your project at /docs/modules/DesignSystem.md

What You Get

✅ Token system - Colors, spacing, typography, radius (never hardcode values)
✅ 5 themes - System, Light, Dark, Aurora, Obsidian
✅ Liquid Glass primitive - SAIGlass with iOS 26 glass and iOS 17–25 Material fallback (new in v2.0)
✅ Premium components - Buttons, inputs, cards, bubbles
✅ BrandConfig - Single place to customize app identity
✅ Accessibility - Dynamic Type, VoiceOver, Reduce Motion
✅ Gradients & motion - Premium visual effects

Time saved: 20-32 hours of design system, theming infrastructure, component library, and testing.

Liquid Glass

v2.0 introduces SAIGlass, a Liquid Glass primitive that uses the iOS 26 Glass material on iOS 26+ and falls back to SwiftUI Material on iOS 17–25. Same call sites, progressive enhancement at runtime. Location: Packages/DesignSystem/Sources/DesignSystem/Materials/SAIGlass.swift

SAIGlassStyle

public enum SAIGlassStyle {
    case regular  // Standard glass surface (cards, toolbars, sheets)
    case clear    // Edge-to-edge hero surfaces (paywall, onboarding)
}

The `.saiGlass` modifier

One-call glass treatment for any view:

// Simple card
VStack { /* content */ }
    .saiGlass(.regular)

// In a shape, interactive
Text("Tap me")
    .padding()
    .saiGlass(.regular, in: Capsule(), interactive: true)

Modifier	Purpose
`.saiGlass(_:in:interactive:)`	Apply a glass material to any view. `in:` accepts any `Shape`; `interactive:` enables tap-response morphing on iOS 26.
`.saiScrollEdgeGlass(_:)`	Glass treatment at scroll edges (under nav bars, tab bars).
`.saiSidebarAdaptable()`	Adaptive sidebar styling for iPad and large displays.
`.saiTabBarMinimize(_:)`	Opt into iOS 26 tab bar minimisation on scroll. iOS 17–25 no-op.

SAIGlassContainer

Use when multiple glass surfaces sit near each other so they sample the same background instead of stacking visually:

SAIGlassContainer {
    RatingCard()
    TipCard()
    UpsellCard()
}

SAITabBarMinimizeStyle

TabView { ... }
    .saiTabBarMinimize(.onScrollDown)  // iOS 26 only; no-op on iOS 17–25

Fighting glass? Stop. Do not pile .background(DSColors.background) or DSColors.background.ignoresSafeArea() onto SwiftUI containers. They block the Material SwiftUI already provides and wreck Liquid Glass on iOS 26. See the Migration Guide for cleanup steps.

BrandConfig (Customize Your App)

Single file to customize app identity. From BrandConfig.swift:

public struct BrandConfig {
    // Change this to your app name (ships with the starter value "App Name")
    public static let appDisplayName = "App Name" // generator:brand appDisplayName

    // Accent color for highlights and CTAs
    public static let accentColor: Color = DSColors.primary

    // SF Symbol for default avatar
    public static let avatarFallbackSymbol = "person.circle.fill" // generator:brand avatarFallbackSymbol

    // Production legal URLs — leave empty until your live HTTPS pages exist.
    // Non-HTTPS / placeholder values resolve to nil (no Release fallback).
    public static let privacyPolicyURLString = ""        // generator:brand privacyPolicyURL
    public static let termsOfServiceURLString = ""       // generator:brand termsOfServiceURL
    public static let subscriptionTermsURLString = ""    // generator:brand subscriptionTermsURL

    // App icon background color (for generated icons)
    public static let appIconBackground: Color = DSColors.primary
}

To rebrand:

Change appDisplayName → Your app name
Update the AccentPrimary color set in Resources/Assets.xcassets
Change avatarFallbackSymbol → Your SF Symbol
Set the legal URL strings to your live HTTPS pages before shipping
Entire app updates automatically

The // generator:brand markers are stable anchors for the App Generator’s identity transforms — a separate product (coming soon). Keep one declaration per line and do not remove the markers. They are inert in the boilerplate itself.

Design Tokens (Production System)

DSColors - Theme-Aware

Every color adapts to the active theme:

// Real usage from auth screen
Text(BrandConfig.appDisplayName)
    .foregroundStyle(DSColors.textPrimary)

Button("Sign In")
    .foregroundStyle(DSColors.accentPrimary)  // Coral in Aurora, blue in default

VStack {}
    .background(DSColors.background)         // Adapts to all 5 themes

Token categories:

Text: textPrimary, textSecondary
Surfaces: background, surface, surfaceElevated
Accents: accentPrimary, accentSecondary
Borders: borderHairline, borderSubtle
Semantic: success, warning, danger

DSSpacing

Consistent spacing scale:

// Usage
.padding(DSSpacing.md)
VStack(spacing: DSSpacing.lg) { }

// Scale: xs (4pt) → sm (8pt) → md (12pt) → lg (16pt) → xl (24pt)

DSTypography

Text styles with Dynamic Type:

// Usage
Text("Title").font(DSTypography.titleL)
Text("Body").font(DSTypography.body)

// Styles: titleXL, titleL, titleM, body, caption, code

DSRadius

Corner radius values:

// Usage
.cornerRadius(DSRadius.md)

// Scale: xs (8pt) → sm (12pt) → md (16pt) → lg (24pt) → xl (32pt)
// Plus DSRadius.card (= lg, 24pt) — the default card radius

UI Components

Buttons
Inputs
Cards & Rows
Other

SAIButton("Primary", style: .primary) { action() }
SAIButton("Secondary", style: .secondary) { action() }
SAIButton("Quiet", style: .quiet, size: .sm) { action() }

SAIInputBar(text: $message, onSend: sendMessage)
SAIInputBar(text: $message, showTokenCount: true, onSend: sendMessage)

SAICard(style: .elevated) {
    // Content
}

SAIListRow(title: "Setting", subtitle: "Value") {
    Image(systemName: "chevron.right")  // trailing accessory
}

SAIAvatar(name: "John Doe", imageURL: url)
ChatBubble(role: .user, text: "Hello")
DSSectionHeader(title: "Section")
ToastCenter.shared.show(ToastMessage(title: "Success!", style: .success))

Theme System

5 Built-in Themes

System

Follows iOS light/dark mode

Light

Always light appearance

Dark

Always dark appearance

Aurora

Premium light — warm cream with coral/peach accents

Obsidian

Premium dark — deep navy with electric cyan accents

Applying Themes

From Settings, persist and apply a theme in one call (SettingsDTO.Theme):

await settingsViewModel.setTheme(.aurora)  // persists + applies app-wide

ThemeManager (in the Core package) owns the live theme and is also reachable directly:

@Environment(ThemeManager.self) private var themeManager
themeManager.selected = .aurora  // applies instantly, without persisting Settings

How It Works

settingsViewModel.setTheme maps SettingsDTO.Theme → ThemeManager.Theme
ThemeManager persists the choice (UserDefaults) and applies the interface style
It posts a "ThemeDidChange" notification
DSColors.setTheme(_:colorScheme:) updates DSColors.activeTheme
Color tokens return theme-specific values and SwiftUI refreshes

Customization Examples

Create Custom Theme

Add Color Set

In Resources/Assets.xcassets, add a color set per token you want to override (e.g. AccentPrimary, Background). Themed values can also be returned in code (see step 3).

Add Theme Cases

Add case myTheme to both theme enums — the persisted SettingsDTO.Theme (Packages/Storage/.../SettingsDTO.swift) and the live ThemeManager.Theme (Packages/Core/Sources/Core/Theme/ThemeManager.swift). Then add the .myTheme branch to the mapping in SettingsViewModel.setTheme(_:), and add a matching case to DSColors.ThemePalette + DSColors.setTheme(_:colorScheme:).

Map Colors

In DSColors.swift, branch on activeTheme:

public static var accentPrimary: Color {
    switch activeTheme {
    case .myTheme:
        return Color("MyThemePrimary", bundle: .module)
    default:
        return named("AccentPrimary", fallback: .blue)
    }
}

Surface in the Picker

The settings appearance picker iterates SettingsDTO.Theme.allCases, so the new case appears automatically once the cases above are wired up.

Create Custom Component

public struct MyCustomCard: View {
    let title: String
    let subtitle: String
    
    public var body: some View {
        VStack(alignment: .leading, spacing: DSSpacing.sm) {
            Text(title)
                .font(DSTypography.titleM)
                .foregroundStyle(DSColors.textPrimary)
            
            Text(subtitle)
                .font(DSTypography.body)
                .foregroundStyle(DSColors.textSecondary)
        }
        .padding(DSSpacing.md)
        .background(DSColors.surface)
        .cornerRadius(DSRadius.md)
    }
}

Animations

Standard motion timings live in SAIMotion and respect Reduce Motion:

// Timings
SAIMotion.quick     // 0.12s — micro-interactions
SAIMotion.standard  // 0.18s — most UI changes
SAIMotion.smooth    // 0.25s — larger transitions

// Springs
SAIMotion.spring        // response 0.3, damping 0.7
SAIMotion.gentleSpring  // subtle bounces

// Accessibility-aware (auto-fallback when Reduce Motion is on)
SAIMotion.adaptiveStandard
SAIMotion.adaptiveSpring

// Usage
.animation(SAIMotion.spring, value: isExpanded)

// Reusable view modifiers
SomeView().pressedEffect(isPressed: isPressed)  // scale + shadow, opacity-only under Reduce Motion
SomeView().shimmer(isActive: true)              // loading shimmer, disabled under Reduce Motion

Accessibility

Built-in support for:

✅ Dynamic Type - All text scales automatically
✅ VoiceOver - All components labeled
✅ High Contrast - Semantic colors adapt
✅ Reduced Motion - Respects system preference
✅ Minimum Touch Targets - 44pt minimum

Key Files

Component	Location
Tokens	`Packages/DesignSystem/Sources/DesignSystem/Tokens/`
Components	`Packages/DesignSystem/Sources/DesignSystem/Components/`
Liquid Glass	`Packages/DesignSystem/Sources/DesignSystem/Materials/SAIGlass.swift`
Colors	`Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets`

Dependencies

None - DesignSystem is independent

Used By

All features - Every UI component
App Shell - Main app screens
Feature modules - Chat, Rating, Settings

Best Practices

Using Tokens

Never hardcode colors
Never hardcode spacing
Use semantic names
Test in all themes

Creating Components

Use design tokens exclusively
Support all themes
Add accessibility labels
Test Dynamic Type
Include preview

Theming

Semantic colors only
Support light + dark
Instant switching
Persist preference

Learn More

Full Documentation

Complete DesignSystem guide

Feature Settings

Theme selection UI

Building Guide

Customize themes

Architecture

See how modules use DesignSystem

Test Coverage

The DesignSystemTests target (token + snapshot tests) runs as part of the workspace suite — ~598 tests across 12 package test targets plus the app test suites, all in one Boilerplate.xctestplan pass. Tests include:

Theme switching
Color mapping
Component snapshots
Accessibility
Dynamic Type

​What You Get

​Liquid Glass

​SAIGlassStyle

​The .saiGlass modifier

​SAIGlassContainer

​SAITabBarMinimizeStyle

​BrandConfig (Customize Your App)

​Design Tokens (Production System)

​DSColors - Theme-Aware

​DSSpacing

​DSTypography

​DSRadius

​UI Components

​Theme System

​5 Built-in Themes

System

Light

Dark

Aurora

Obsidian

​Applying Themes

​How It Works

​Customization Examples

​Create Custom Theme

​Create Custom Component

​Animations

​Accessibility

​Key Files

​Dependencies

​Used By

​Best Practices

​Learn More

Full Documentation

Feature Settings

Building Guide

Architecture

​Test Coverage

What You Get

Liquid Glass

SAIGlassStyle

The `.saiGlass` modifier

SAIGlassContainer

SAITabBarMinimizeStyle

BrandConfig (Customize Your App)

Design Tokens (Production System)

DSColors - Theme-Aware

DSSpacing

DSTypography

DSRadius

UI Components

Theme System

5 Built-in Themes

Applying Themes

How It Works

Customization Examples

Create Custom Theme

Create Custom Component

Animations

Accessibility

Key Files

Dependencies

Used By

Best Practices

Learn More

Test Coverage