CasinoGames/BRANDING_IMPLEMENTATION_GUIDE.md

# Branding Implementation Guide

A step-by-step guide to implementing the CasinoKit branding system (app icon and launch screen) in your casino game app.

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Step 1: Copy Branding Files](#step-1-copy-branding-files)
4. [Step 2: Create BrandingConfig.swift](#step-2-create-brandingconfigswift)
5. [Step 3: Add Launch Screen to App Entry Point](#step-3-add-launch-screen-to-app-entry-point)
6. [Step 4: Add Branding Tools to Settings (Optional)](#step-4-add-branding-tools-to-settings-optional)
7. [Step 5: Generate Your App Icon](#step-5-generate-your-app-icon)
8. [Step 6: Add Icon to Xcode Assets](#step-6-add-icon-to-xcode-assets)
9. [Complete Example](#complete-example)
10. [Troubleshooting](#troubleshooting)

---

## Overview

The CasinoKit branding system provides:

- **AppIconView**: A customizable icon design with gradient backgrounds, SF Symbols, and text
- **LaunchScreenView**: An animated launch screen that matches your icon
- **AppLaunchView**: A wrapper that seamlessly transitions from launch to app
- **IconGeneratorView**: A development tool to generate and export icon images
- **BrandingPreviewView**: A preview tool to see icons and launch screens side-by-side

**Key Files in CasinoKit:**
- `AppIconView.swift` - Icon design view
- `LaunchScreenView.swift` - Launch screen design view
- `AppLaunchView.swift` - Launch wrapper with animation
- `IconGeneratorView.swift` - Icon export tool
- `IconRenderer.swift` - Rendering utilities
- `BrandingPreviewView.swift` - Preview tool

---

## Prerequisites

### If Using CasinoKit Package

Your app must have `CasinoKit` as a dependency. No additional files needed—everything is available through `import CasinoKit`.

### If You Copied the Branding Folder

If you manually copied the branding views from CasinoKit into your app, ensure you have:

1. All 6 files from `CasinoKit/Sources/CasinoKit/Views/Branding/`:
   - `AppIconView.swift`
   - `LaunchScreenView.swift`
   - `AppLaunchView.swift`
   - `IconGeneratorView.swift`
   - `IconRenderer.swift`
   - `BrandingPreviewView.swift`

2. Dependencies these files require:
   - `DiamondPatternView.swift` (used by `AppIconView`)
   - `DebugSection.swift` (if using debug tools)

---

## Step 1: Copy Branding Files

**Skip this step if using CasinoKit as a package dependency.**

If copying manually, create a `Theme/` folder in your app target and copy all branding files:

```
YourApp/
  YourApp/
    Theme/
      AppIconView.swift
      LaunchScreenView.swift
      AppLaunchView.swift
      IconGeneratorView.swift
      IconRenderer.swift
      BrandingPreviewView.swift
      BrandingConfig.swift  ← You'll create this in Step 2
```

**Important:** Ensure you also have `DiamondPatternView.swift` if `AppIconView` references it, or copy that pattern code inline.

---

## Step 2: Create BrandingConfig.swift

Create a new Swift file in your app's `Theme/` folder called `BrandingConfig.swift`. This file defines your game's branding.

### Template

```swift
//
//  BrandingConfig.swift
//  YourGame
//
//  App-specific branding configurations for icons and launch screens.
//

import SwiftUI
import CasinoKit  // Remove this line if not using CasinoKit package

// MARK: - App Icon Configuration

extension AppIconConfig {
    /// YourGame app icon configuration.
    static let yourGame = AppIconConfig(
        title: "YOUR GAME",           // App name (uppercase looks best)
        subtitle: "21",                 // Optional: number or short text below icon
        iconSymbol: "suit.club.fill",   // SF Symbol for the main icon
        primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35),   // Top gradient color
        secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25), // Bottom gradient color
        accentColor: .yellow            // Color for icon and text
    )
}

// MARK: - Launch Screen Configuration

extension LaunchScreenConfig {
    /// YourGame launch screen configuration.
    static let yourGame = LaunchScreenConfig(
        title: "YOUR GAME",            // App name (uppercase looks best)
        subtitle: "21",                 // Optional: appears below icon symbols
        tagline: "Beat the Dealer",     // Optional: tagline at bottom
        iconSymbols: [                  // 1-3 SF Symbols for the launch logo
            "suit.club.fill",
            "suit.diamond.fill"
        ],
        primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35),   // Top gradient color
        secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25), // Bottom gradient color
        accentColor: .yellow            // Color for text and accents
    )
}
```

### Customization Tips

**Title:**
- Use uppercase for a casino aesthetic
- Keep it concise (6-9 characters max)
- The view automatically scales longer titles

**Subtitle:**
- Optional, best for short numbers or text ("21", "DELUXE", etc.)
- Appears larger and more prominent than the title

**Icon Symbol:**
- Use SF Symbols names (e.g., `"suit.spade.fill"`, `"diamond.fill"`)
- Browse available symbols in Xcode: Editor → Insert SF Symbol
- Card suits work great: `suit.spade.fill`, `suit.heart.fill`, `suit.diamond.fill`, `suit.club.fill`

**Colors:**
- Use `Color(red:green:blue:)` with values 0.0-1.0
- Primary color = top of gradient
- Secondary color = bottom of gradient (usually darker)
- Accent color = icon symbol and text highlights

**Launch Screen Icon Symbols:**
- Use 1-3 symbols for visual variety
- Hearts and diamonds automatically render red
- Spades and clubs render white

### Real Examples

**Blackjack:**
```swift
extension AppIconConfig {
    static let blackjack = AppIconConfig(
        title: "BLACKJACK",
        subtitle: "21",
        iconSymbol: "suit.club.fill",
        primaryColor: Color(red: 0.05, green: 0.35, blue: 0.15),    // Green felt
        secondaryColor: Color(red: 0.03, green: 0.2, blue: 0.1),
        accentColor: .yellow
    )
}

extension LaunchScreenConfig {
    static let blackjack = LaunchScreenConfig(
        title: "BLACKJACK",
        subtitle: "21",
        tagline: "Beat the Dealer",
        iconSymbols: ["suit.club.fill", "suit.diamond.fill"],
        primaryColor: Color(red: 0.05, green: 0.35, blue: 0.15),
        secondaryColor: Color(red: 0.03, green: 0.2, blue: 0.1),
        accentColor: .yellow
    )
}
```

**Baccarat:**
```swift
extension AppIconConfig {
    static let baccarat = AppIconConfig(
        title: "BACCARAT",
        iconSymbol: "suit.spade.fill",
        primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35),      // Blue elegant
        secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25)
    )
}

extension LaunchScreenConfig {
    static let baccarat = LaunchScreenConfig(
        title: "BACCARAT",
        tagline: "The Classic Casino Card Game",
        iconSymbols: ["suit.spade.fill", "suit.heart.fill"]
    )
}
```

---

## Step 3: Add Launch Screen to App Entry Point

Update your `@main` App struct to wrap your content with `AppLaunchView`.

### Before

```swift
@main
struct YourGameApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

### After

```swift
import SwiftUI
import CasinoKit  // If using the package

@main
struct YourGameApp: App {
    var body: some Scene {
        WindowGroup {
            AppLaunchView(config: .yourGame) {
                ContentView()
            }
        }
    }
}
```

**What this does:**
- Shows an animated launch screen for ~2 seconds
- Fades smoothly into your main content
- Creates a polished, professional app opening experience

**Note:** Replace `.yourGame` with the static property name you defined in `BrandingConfig.swift` (e.g., `.blackjack`, `.poker`, `.roulette`).

---

## Step 4: Add Branding Tools to Settings (Optional)

Add debug tools to your settings view so you can easily generate and preview icons during development.

### If Using CasinoKit Package

Add this to your settings view inside a `#if DEBUG` block:

```swift
#if DEBUG
SheetSection(title: "DEBUG", icon: "ant.fill") {
    BrandingDebugRows(
        iconConfig: .yourGame,
        launchConfig: .yourGame,
        appName: "YourGame"
    )
}
#endif
```

### Full Example in Settings

```swift
import SwiftUI
import CasinoKit

struct SettingsView: View {
    @Environment(\.dismiss) private var dismiss
    
    var body: some View {
        SheetContainerView(
            title: "Settings",
            content: {
                // ... your normal settings sections ...
                
                // DEBUG section at the bottom
                #if DEBUG
                SheetSection(title: "DEBUG", icon: "ant.fill") {
                    BrandingDebugRows(
                        iconConfig: .yourGame,
                        launchConfig: .yourGame,
                        appName: "YourGame"
                    )
                }
                #endif
            },
            onCancel: nil,
            onDone: {
                dismiss()
            }
        )
    }
}
```

**What this adds:**
- **Icon Generator** button: Generates and saves a 1024px PNG to the Files app
- **Branding Preview** button: Shows a live preview of your icon and launch screen

**Important:** This only appears in DEBUG builds and will automatically be excluded from App Store releases.

---

## Step 5: Generate Your App Icon

Now it's time to create your actual app icon image.

### Method 1: Using IconGeneratorView (Recommended)

1. **Build and run your app** (simulator or device)
2. **Open Settings** in your app
3. **Scroll to the DEBUG section** (only visible in DEBUG builds)
4. **Tap "Icon Generator"**
5. **Tap "Generate & Save Icon"**
6. **Wait for confirmation**: "✅ Icon saved to Documents folder!"

The icon is now saved as `AppIcon.png` (1024×1024) in your app's Documents folder.

### Method 2: Using Xcode Previews

1. Open `BrandingConfig.swift` in Xcode
2. Add a preview at the bottom:

```swift
#Preview("App Icon") {
    AppIconView(config: .yourGame, size: 512)
        .clipShape(.rect(cornerRadius: 512 * 0.22))
        .padding()
        .background(Color.gray)
}
```

3. Open the Canvas (Editor → Canvas)
4. Take a screenshot of the preview
5. Crop and scale to 1024×1024 in an image editor

### Method 3: Programmatic Export

Create a temporary view or function:

```swift
@MainActor
func exportIcon() {
    let config = AppIconConfig.yourGame
    let view = AppIconView(config: config, size: 1024)
    let renderer = ImageRenderer(content: view)
    renderer.scale = 1.0
    
    if let image = renderer.uiImage,
       let data = image.pngData() {
        let url = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
            .appending(path: "AppIcon.png")
        try? data.write(to: url)
        print("Icon saved to: \(url.path)")
    }
}
```

---

## Step 6: Add Icon to Xcode Assets

### Retrieve the Icon from Device/Simulator

**On Simulator:**
1. Open **Finder**
2. Go to: `~/Library/Developer/CoreSimulator/Devices/`
3. Find your simulator device folder
4. Navigate to: `data/Containers/Data/Application/[YourApp]/Documents/`
5. Copy `AppIcon.png` to your Mac desktop

**On Physical Device:**
1. Open the **Files** app on your device
2. Navigate to: **On My iPhone** → **YourGame**
3. Find `AppIcon.png`
4. **AirDrop** or **share** it to your Mac

**Alternative (Xcode):**
1. In Xcode, go to **Window** → **Devices and Simulators**
2. Select your device/simulator
3. Find your app in the Installed Apps list
4. Click the **⚙️ gear** icon → **Download Container**
5. Right-click the downloaded `.xcappdata` file → **Show Package Contents**
6. Navigate to `AppData/Documents/` and copy `AppIcon.png`

### Add to Xcode Assets

1. **Open your Xcode project**
2. **Navigate to** `Assets.xcassets` in the Project Navigator
3. **Click on AppIcon** (the app icon asset)
4. **Drag `AppIcon.png`** from Finder into the **1024×1024** slot (labeled "iOS App Store")
5. **Xcode automatically generates** all required sizes from this single image

**Important:** Modern iOS projects only need the 1024×1024 image. Xcode generates all other sizes automatically.

### Verify the Icon

1. **Build and run** your app
2. **Press the Home button** (or swipe up)
3. Check that your new icon appears on the home screen
4. If it doesn't update immediately, **delete the app** and reinstall

---

## Complete Example

Here's a full example for a Poker game:

### File: `Poker/Theme/BrandingConfig.swift`

```swift
//
//  BrandingConfig.swift
//  Poker
//

import SwiftUI
import CasinoKit

extension AppIconConfig {
    static let poker = AppIconConfig(
        title: "POKER",
        iconSymbol: "suit.diamond.fill",
        primaryColor: Color(red: 0.2, green: 0.05, blue: 0.1),
        secondaryColor: Color(red: 0.1, green: 0.02, blue: 0.05),
        accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)  // Gold
    )
}

extension LaunchScreenConfig {
    static let poker = LaunchScreenConfig(
        title: "POKER",
        tagline: "All In",
        iconSymbols: ["suit.diamond.fill", "suit.heart.fill", "suit.club.fill"],
        primaryColor: Color(red: 0.2, green: 0.05, blue: 0.1),
        secondaryColor: Color(red: 0.1, green: 0.02, blue: 0.05),
        accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)
    )
}
```

### File: `Poker/PokerApp.swift`

```swift
import SwiftUI
import CasinoKit

@main
struct PokerApp: App {
    var body: some Scene {
        WindowGroup {
            AppLaunchView(config: .poker) {
                ContentView()
            }
        }
    }
}
```

### File: `Poker/Views/SettingsView.swift`

```swift
import SwiftUI
import CasinoKit

struct SettingsView: View {
    @Environment(\.dismiss) private var dismiss
    
    var body: some View {
        SheetContainerView(
            title: "Settings",
            content: {
                // Game settings sections...
                
                SheetSection(title: "SOUND", icon: "speaker.wave.2.fill") {
                    // Sound settings...
                }
                
                #if DEBUG
                SheetSection(title: "DEBUG", icon: "ant.fill") {
                    BrandingDebugRows(
                        iconConfig: .poker,
                        launchConfig: .poker,
                        appName: "Poker"
                    )
                }
                #endif
            },
            onDone: {
                dismiss()
            }
        )
    }
}
```

---

## Troubleshooting

### Issue: Can't find `AppIconView` or other branding types

**Solution:**
- If using CasinoKit package: Ensure `import CasinoKit` is at the top of your file
- If copying manually: Ensure all 6 branding files are in your app target
- Check that files are added to your target's "Compile Sources" in Build Phases

### Issue: Launch screen doesn't appear

**Solution:**
- Verify `AppLaunchView` wraps your content in the App struct
- Check that you're using the correct config name (e.g., `.poker` not `.example`)
- Ensure the config extension is defined in `BrandingConfig.swift`

### Issue: Icon looks cut off at the edges

**Explanation:** iOS applies a superellipse mask to all app icons. The branding system accounts for this, but if you see clipping:

**Solution:**
- Don't add rounded corners yourself—iOS does this automatically
- Ensure decorative borders are inset from edges
- The system is designed to work with iOS's mask; trust the 22% corner radius preview

### Issue: "Icon saved" message appears but can't find the file

**Solution:**
- Open the **Files** app on your device/simulator
- Navigate to: **Browse** → **On My iPhone/iPad** → **[Your App Name]**
- If folder doesn't exist, try granting Files access in Settings

**Alternative:** Use Xcode's Devices and Simulators window to download the app container (see Step 6).

### Issue: Icon doesn't update after adding to Assets

**Solution:**
1. **Clean build folder**: Product → Clean Build Folder (Cmd+Shift+K)
2. **Delete app** from device/simulator
3. **Rebuild and reinstall**
4. If still not working, check that the 1024×1024 slot is filled in Assets.xcassets

### Issue: `BrandingDebugRows` not showing in settings

**Solution:**
- Ensure you're running a DEBUG build (not Release)
- Wrap the section in `#if DEBUG ... #endif`
- Verify `import CasinoKit` if using the package
- Check that your settings view is inside a `NavigationStack` (required for navigation rows)

### Issue: Colors don't match between icon and launch screen

**Solution:**
- Ensure both configs use identical color values
- Copy-paste color definitions to avoid typos
- Consider extracting colors to a shared constant:

```swift
extension Color {
    static let pokerPrimary = Color(red: 0.2, green: 0.05, blue: 0.1)
    static let pokerSecondary = Color(red: 0.1, green: 0.02, blue: 0.05)
}

extension AppIconConfig {
    static let poker = AppIconConfig(
        title: "POKER",
        iconSymbol: "suit.diamond.fill",
        primaryColor: .pokerPrimary,
        secondaryColor: .pokerSecondary
    )
}
```

### Issue: Title text is too small or too large

**Solution:** The system automatically scales titles based on length:
- **6 characters or less**: Full size (100%)
- **7 characters**: 95% scale
- **8 characters**: 85% scale
- **9 characters**: 75% scale
- **10+ characters**: 65% scale

If your title is very long, consider:
- Using an abbreviation in the icon
- Using subtitle for additional text
- Manually adjusting the `titleSize` calculation in `AppIconView.swift`

---

## Additional Resources

### Color Palette Ideas

**Classic Casino:**
```swift
primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35)    // Deep blue
secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25)
accentColor: .yellow
```

**Luxury Gold:**
```swift
primaryColor: Color(red: 0.2, green: 0.15, blue: 0.05)   // Deep gold
secondaryColor: Color(red: 0.1, green: 0.08, blue: 0.02)
accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)     // Bright gold
```

**Green Felt:**
```swift
primaryColor: Color(red: 0.05, green: 0.35, blue: 0.15)  // Casino green
secondaryColor: Color(red: 0.03, green: 0.2, blue: 0.1)
accentColor: .yellow
```

**Elegant Red:**
```swift
primaryColor: Color(red: 0.3, green: 0.05, blue: 0.1)    // Deep red
secondaryColor: Color(red: 0.15, green: 0.02, blue: 0.05)
accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)
```

### SF Symbol Recommendations

**Card Suits:**
- `suit.spade.fill` - Classic, elegant
- `suit.heart.fill` - Warm, friendly
- `suit.diamond.fill` - Luxurious
- `suit.club.fill` - Traditional

**Other Casino Icons:**
- `diamond.fill` - Luxury, wealth
- `star.fill` - Premium, winning
- `crown.fill` - VIP, royalty
- `dollarsign.circle.fill` - Money, stakes

### Launch Screen Animation Timing

The default timing is:
- **Logo fade-in**: 0.6 seconds
- **Tagline fade-in**: 0.6 seconds (delayed by 0.3s)
- **Total display**: 2.0 seconds
- **Fade-out**: 0.5 seconds

To customize, modify `AppLaunchView.swift`:

```swift
.task {
    try? await Task.sleep(for: .seconds(3.0))  // Change display duration
    withAnimation(.easeOut(duration: 1.0)) {    // Change fade-out duration
        showLaunchScreen = false
    }
}
```

---

## Summary Checklist

- [ ] Copy branding files from CasinoKit or ensure package dependency is set up
- [ ] Create `BrandingConfig.swift` with your game's configurations
- [ ] Add `AppLaunchView` wrapper to your App entry point
- [ ] (Optional) Add `BrandingDebugRows` to your settings view
- [ ] Build and run app in DEBUG mode
- [ ] Generate icon using Icon Generator tool
- [ ] Retrieve icon PNG from device/simulator
- [ ] Add 1024×1024 PNG to Assets.xcassets AppIcon slot
- [ ] Clean build and reinstall to verify icon appears
- [ ] Test launch screen animation on device

---

**Need Help?**

- Check the `BrandingPreviewView` to see your icon and launch screen side-by-side
- Use Xcode previews to iterate on colors and layout quickly
- Test on multiple device sizes to ensure text scales properly
- Remember: DEBUG tools are automatically excluded from Release builds

**Happy Branding! 🎰✨**