Bedrock

A foundational design system and UI component library for building consistent, beautiful SwiftUI applications.

Overview

Bedrock is designed to be the foundation upon which apps are built, providing:

• Design System: Consistent spacing, typography, colors, and animations
• Color Protocols: Define consistent color naming with custom palettes per app
• Settings Components: Ready-to-use toggle, picker, and selector views
• Sound & Haptics: Generic sound manager with haptic feedback support
• Onboarding: First-time user experience and contextual hints
• Cloud Sync: Generic iCloud data synchronization
• Visual Effects: Confetti celebrations, pulsing animations
• Utilities: Device detection, debugging tools, and more

---

📚 Implementation Guides for AI Agents

Before implementing any Bedrock features in a new app, read the relevant guide(s) below. Each guide contains step-by-step instructions, templates, and troubleshooting information.

Guide Reference

Guide	Path	Purpose
Theme Guide	Sources/Bedrock/Theme/THEME_GUIDE.md	Create custom color themes using Bedrock's protocol-based theming system
Branding Guide	Sources/Bedrock/Branding/BRANDING_GUIDE.md	Set up app icons, launch screens, and branded launch animations
Settings Guide	Sources/Bedrock/Views/Settings/SETTINGS_GUIDE.md	Build branded settings screens with reusable UI components

Implementation Checklist

Use this checklist when setting up a new app with Bedrock:

🎨 Theming (Required for all apps)

• Read: THEME_GUIDE.md
• Create [AppName]Theme.swift in Shared/Theme/
• Define custom SurfaceColorProvider with your brand colors
• Define custom AccentColorProvider for interactive elements
• Create typealiases for easy access (e.g., AppSurface, AppAccent)
• Import Bedrock: Add import Bedrock to all files using theme/design constants (Required)
• Asset Catalog Format: Ensure Contents.json uses the "color" key and "luminosity" appearance (See THEME_GUIDE.md for template)
• Legibility Alignment: Apply .preferredColorScheme(.dark) to the root view if using a dark theme to ensure system text resolves to white (Required for legibility)
• Apply theme colors to all views (never use hardcoded colors)

🚀 Branding & Launch Screen (Required for all apps)

• Read: BRANDING_GUIDE.md
• Create BrandingConfig.swift in Shared/
• Define Color.Branding.primary, .secondary, .accent
• Create AppIconConfig extension for your app
• Create LaunchScreenConfig extension for your app
• Create LaunchScreen.storyboard with matching brand color (Mandatory for no-flash launch)
• Add INFOPLIST_KEY_UILaunchStoryboardName to build settings
• Remove INFOPLIST_KEY_UILaunchScreen_* settings from project (Unreliable)
• Wrap app entry point with AppLaunchView inside a ZStack
• Generate and export app icon using IconGeneratorView

⚙️ Settings Screen (When adding settings)

• Read: SETTINGS_GUIDE.md
• Use SettingsToggle, SettingsSlider, SegmentedPicker components
• Apply theme colors via AppSurface, AppAccent, etc.
• Use SettingsCard for grouped sections
• Use SettingsNavigationRow for navigation links
• Add #if DEBUG section for development tools

Quick Start Order

When building a new app from scratch:

1. First: Read THEME_GUIDE.md → Create your app's color theme
2. Second: Read BRANDING_GUIDE.md → Set up icons and launch screen
3. Third: Read SETTINGS_GUIDE.md → Build your settings view

---

Installation

Add Bedrock as a dependency in your Package.swift:

dependencies: [
    .package(url: "ssh://git@192.168.1.128:220/mbrucedogs/Bedrock.git", branch: "master")
]

Then add it to your target:

.target(
    name: "YourApp",
    dependencies: ["Bedrock"]
)

Usage

Design Constants

Use the Design enum for consistent spacing, sizing, and styling:

import SwiftUI
import Bedrock

struct MyView: View {
    var body: some View {
        VStack(spacing: Design.Spacing.medium) {
            Text("Hello")
                .font(.title)
                .padding(Design.Spacing.large)
            
            Button("Tap Me") { }
                .clipShape(.rect(cornerRadius: Design.CornerRadius.medium))
        }
    }
}

Color System

Bedrock provides a protocol-based color system that enforces consistent naming while allowing apps to define their own palettes.

Using Default Colors

Bedrock includes neutral default colors that work out of the box:

Text("Primary Text")
    .foregroundStyle(Color.TextColors.primary)

Text("Secondary Text")
    .foregroundStyle(Color.TextColors.secondary)

VStack { }
    .background(Color.Surface.primary)

Creating Custom Color Themes

Apps can define custom color palettes by conforming to the color protocols:

// Define custom accent colors
public enum MyAppAccentColors: AccentColorProvider {
    public static let primary = Color(red: 0.9, green: 0.75, blue: 0.3)
    public static let light = Color(red: 1.0, green: 0.85, blue: 0.4)
    public static let dark = Color(red: 0.7, green: 0.55, blue: 0.2)
    public static let secondary = Color(red: 0.2, green: 0.7, blue: 0.7)
}

// Create a complete theme
public enum MyAppTheme: AppColorTheme {
    public typealias Surface = DefaultSurfaceColors     // Reuse Bedrock defaults
    public typealias Text = DefaultTextColors
    public typealias Accent = MyAppAccentColors         // Custom accents
    public typealias Button = DefaultButtonColors
    public typealias Status = DefaultStatusColors
    public typealias Border = DefaultBorderColors
    public typealias Interactive = DefaultInteractiveColors
}

// Use in views
Button("Action") { }
    .background(MyAppTheme.Accent.primary)

Available Color Protocols

Protocol	Properties
SurfaceColorProvider	primary, secondary, tertiary, overlay, card, groupedFill, sectionFill
TextColorProvider	primary, secondary, tertiary, disabled, placeholder, inverse
AccentColorProvider	primary, light, dark, secondary
ButtonColorProvider	primaryLight, primaryDark, secondary, destructive, cancelText
StatusColorProvider	success, warning, error, info
BorderColorProvider	subtle, standard, emphasized, selected
InteractiveColorProvider	selected, hover, pressed, focus

Sound & Haptics

Generic sound manager that works with any app-defined sounds:

// Define your app's sounds
enum MyAppSound: String, AppSound {
    case success, error, notification
    
    var resourceName: String { rawValue }
    var resourceExtension: String { "mp3" }
    var bundle: Bundle { .main }
    var fallbackSystemSoundID: UInt32? { nil }
}

// Play sounds and haptics
let soundManager = SoundManager.shared
soundManager.play(MyAppSound.success)
soundManager.playHaptic(.success)
soundManager.playHaptic(.light)

Onboarding State

Track first-time user experience and contextual hints:

@Observable
class AppState {
    let onboarding = OnboardingState(appIdentifier: "myApp")
    
    var showWelcome: Bool {
        !onboarding.hasCompletedWelcome
    }
}

// Register hints for skip functionality
onboarding.registerHintKeys("firstBet", "settings", "tutorial")

// Check if hints should show
if onboarding.shouldShowHint("firstBet") {
    // Show hint
    onboarding.markHintShown("firstBet")
}

// Complete onboarding
onboarding.completeWelcome()

Cloud Sync

Generic iCloud synchronization for app data:

// Define your persisted data
struct MyAppData: PersistableData {
    static var dataIdentifier = "myApp"
    static var empty = MyAppData()
    
    var syncPriority: Int { score }
    var lastModified: Date = .now
    var score: Int = 0
}

// Create sync manager
let syncManager = CloudSyncManager<MyAppData>()

// Access and modify data
syncManager.data.score += 10
syncManager.save()

Visual Effects

Confetti

ZStack {
    MainContentView()
    
    if showCelebration {
        ConfettiView(colors: [.red, .blue, .gold], count: 50)
    }
}

Pulsing Attention

Button("Tap Here") { }
    .pulsing(isActive: shouldHighlight, color: .white)

Settings Components

Ready-to-use settings UI components:

// Toggle with title and subtitle
SettingsToggle(
    title: "Notifications",
    subtitle: "Receive push notifications",
    isOn: $notificationsEnabled
)

// Slider with format helpers
SettingsSlider(
    title: "Brightness",
    subtitle: "Adjusts the brightness",
    value: $brightness,
    format: SliderFormat.percentage,
    leadingIcon: Image(systemName: "sun.min"),
    trailingIcon: Image(systemName: "sun.max.fill")
)

// Segmented picker
SegmentedPicker(
    title: "Theme",
    options: [("Light", "light"), ("Dark", "dark")],
    selection: $theme
)

// Selectable row with badge
SelectableRow(
    title: "Premium Plan",
    subtitle: "Unlock all features",
    isSelected: plan == .premium,
    badge: { BadgePill(text: "$9.99", isSelected: plan == .premium) },
    action: { plan = .premium }
)

Debug Tools

MyComplexView()
    .debugBorder(isDebugMode, color: .red, label: "Header")

Device Detection

Adapt your UI based on device characteristics:

if DeviceInfo.isPad {
    SidebarView()
} else {
    TabBarView()
}

if DeviceInfo.isLandscape {
    HorizontalLayout()
}

Design System Reference

Spacing

Name	Value	Usage
xxxSmall	1pt	Hairline spacing
xxSmall	2pt	Minimal spacing
xSmall	4pt	Tight spacing
small	8pt	Compact spacing
medium	12pt	Default spacing
large	16pt	Comfortable spacing
xLarge	20pt	Generous spacing
xxLarge	24pt	Section spacing
xxxLarge	32pt	Large section spacing

Opacity

Name	Value	Usage
verySubtle	0.05	Barely visible
subtle	0.1	Subtle backgrounds
hint	0.2	Hints and disabled states
light	0.3	Light overlays
medium	0.5	Medium emphasis
strong	0.7	Strong emphasis
heavy	0.8	Heavy overlays
almostFull	0.9	Nearly opaque

Animation

Name	Value	Usage
quick	0.3s	Quick transitions
standard	0.5s	Standard animations
springDuration	0.4s	Spring animations
staggerDelay	0.1s	Staggered animations

Requirements

• iOS 18.0+
• macOS 15.0+
• Swift 6.0+

License

Proprietary - All rights reserved.