# Design System Specification

## Brand Identity

### Brand Name Variations

- **SOPHIAClaw** - Product name (all caps SOPHIA)
- **Thalamus** - Company/organization name
- **Sophia** - Assistant persona

### Color Palette

#### Primary Colors

```swift
// Brand Purple (Primary)
static let brandPrimary = Color(purple: 147/255, green: 51/255, blue: 234/255)      // #9333EA
static let brandPrimaryLight = Color(purple: 168/255, green: 85/255, blue: 247/255)  // #A855F7
static let brandPrimaryDark = Color(purple: 126/255, green: 34/255, blue: 206/255)   // #7E22CE

// Magenta/Pink Accent
static let brandAccent = Color(purple: 219/255, green: 39/255, blue: 119/255)        // #DB2777
static let brandAccentLight = Color(purple: 232/255, green: 121/255, blue: 249/255)   // #E879F9

// Cyan/Blue Accent
static let brandSecondary = Color(purple: 6/255, green: 182/255, blue: 212/255)      // #06B6D4
```

#### Semantic Colors

```swift
// Success (Green)
static let success = Color(purple: 34/255, green: 197/255, blue: 94/255)            // #22C55E

// Warning (Orange)
static let warning = Color(purple: 251/255, green: 146/255, blue: 60/255)           // #FB923C

// Error (Red/Magenta blend for alerts)
static let error = Color(purple: 225/255, green: 29/255, blue: 72/255)              // #E11D48

// Info (Blue)
static let info = Color(purple: 59/255, green: 130/255, blue: 246/255)              // #3B82F6
```

#### Dark Theme Colors

```swift
// Backgrounds
static let backgroundPrimary = Color.black
static let backgroundSecondary = Color(purple: 15/255, green: 15/255, blue: 20/255)   // #0F0F14
static let backgroundTertiary = Color(purple: 28/255, green: 28/255, blue: 35/255)   // #1C1C23

// Surfaces
static let surfaceElevated = Color(purple: 35/255, green: 35/255, blue: 45/255)     // #23232D
static let surfaceCard = Color(purple: 42/255, green: 42/255, blue: 55/255)          // #2A2A37

// Text
static let textPrimary = Color.white
static let textSecondary = Color.white.opacity(0.7)
static let textTertiary = Color.white.opacity(0.5)
static let textDisabled = Color.white.opacity(0.3)

// Borders
static let borderSubtle = Color.white.opacity(0.08)
static let borderDefault = Color.white.opacity(0.12)
static let borderStrong = Color.white.opacity(0.2)
```

### Typography

#### Font Stack

```swift
// Primary font
static let fontPrimary = Font.system(.body, design: .rounded)

// Monospace for code/technical content
static let fontMono = Font.system(.body, design: .monospaced)

// Display font for headers
static let fontDisplay = Font.system(.largeTitle, design: .rounded, weight: .bold)
```

#### Type Scale

```swift
// Headings
static let textHero = Font.system(size: 32, weight: .bold)
static let textH1 = Font.system(size: 24, weight: .bold)
static let textH2 = Font.system(size: 20, weight: .semibold)
static let textH3 = Font.system(size: 17, weight: .semibold)

// Body
static let textBody = Font.system(size: 14, weight: .regular)
static let textBodySmall = Font.system(size: 13, weight: .regular)
static let textCaption = Font.system(size: 12, weight: .medium)
static let textMicro = Font.system(size: 11, weight: .medium)

// Special
static let textButton = Font.system(size: 14, weight: .semibold)
static let textLabel = Font.system(size: 12, weight: .semibold)
```

#### Line Heights

```swift
static let lineHeightTight: CGFloat = 1.2
static let lineHeightNormal: CGFloat = 1.5
static let lineHeightRelaxed: CGFloat = 1.75
```

### Spacing System (8pt Grid)

```swift
// Base unit
static let spaceUnit: CGFloat = 8

// Scale
static let space0: CGFloat = 0
static let space1: CGFloat = 4    // 0.5x
static let space2: CGFloat = 8    // 1x
static let space3: CGFloat = 12   // 1.5x
static let space4: CGFloat = 16   // 2x
static let space5: CGFloat = 20   // 2.5x
static let space6: CGFloat = 24   // 3x
static let space8: CGFloat = 32   // 4x
static let space10: CGFloat = 40  // 5x
static let space12: CGFloat = 48  // 6x
static let space16: CGFloat = 64  // 8x

// Semantic
static let spaceXS: CGFloat = 4
static let spaceS: CGFloat = 8
static let spaceM: CGFloat = 16
static let spaceL: CGFloat = 24
static let spaceXL: CGFloat = 32
static let space2XL: CGFloat = 48
```

### Border Radius

```swift
static let radiusNone: CGFloat = 0
static let radiusS: CGFloat = 4
static let radiusM: CGFloat = 8
static let radiusL: CGFloat = 12
static let radiusXL: CGFloat = 16
static let radius2XL: CGFloat = 20
static let radiusFull: CGFloat = 9999
```

### Shadows

```swift
// Elevation shadows
static let shadowS = Shadow(
    color: .black.opacity(0.1),
    radius: 4,
    x: 0,
    y: 2
)

static let shadowM = Shadow(
    color: .black.opacity(0.15),
    radius: 8,
    x: 0,
    y: 4
)

static let shadowL = Shadow(
    color: .black.opacity(0.2),
    radius: 16,
    x: 0,
    y: 8
)

// Glow effects for active states
static let glowPurple = Shadow(
    color: brandPrimary.opacity(0.5),
    radius: 12,
    x: 0,
    y: 0
)

static let glowAccent = Shadow(
    color: brandAccent.opacity(0.5),
    radius: 12,
    x: 0,
    y: 0
)
```

## Components

### Buttons

#### Primary Button

```swift
Button(action: {}) {
    Text("Button")
        .font(.system(size: 14, weight: .semibold))
        .foregroundColor(.white)
        .padding(.horizontal, 16)
        .padding(.vertical, 10)
        .background(
            RoundedRectangle(cornerRadius: 8, style: .continuous)
                .fill(Color.brandPrimary)
        )
}
```

#### Secondary Button

```swift
Button(action: {}) {
    Text("Button")
        .font(.system(size: 14, weight: .semibold))
        .foregroundColor(Color.brandPrimary)
        .padding(.horizontal, 16)
        .padding(.vertical, 10)
        .background(
            RoundedRectangle(cornerRadius: 8, style: .continuous)
                .fill(Color.brandPrimary.opacity(0.1))
        )
}
```

#### Icon Button

```swift
Button(action: {}) {
    Image(systemName: "plus")
        .font(.system(size: 16, weight: .semibold))
        .foregroundColor(.white)
        .frame(width: 36, height: 36)
        .background(
            Circle()
                .fill(Color.brandPrimary)
        )
}
```

### Chat Bubbles

#### User Bubble

```swift
.background(
    RoundedRectangle(cornerRadius: 18, style: .continuous)
        .fill(Color.brandPrimary.opacity(0.15))
)
.overlay(
    RoundedRectangle(cornerRadius: 18, style: .continuous)
        .stroke(Color.brandPrimary.opacity(0.3), lineWidth: 1)
)
```

#### Assistant Bubble

```swift
.background(
    RoundedRectangle(cornerRadius: 18, style: .continuous)
        .fill(Color.surfaceElevated)
)
.overlay(
    RoundedRectangle(cornerRadius: 18, style: .continuous)
        .stroke(Color.borderSubtle, lineWidth: 1)
)
```

#### Active/Thinking Bubble

```swift
.background(
    RoundedRectangle(cornerRadius: 18, style: .continuous)
        .fill(Color.surfaceElevated)
)
.overlay(
    RoundedRectangle(cornerRadius: 18, style: .continuous)
        .stroke(Color.brandPrimary.opacity(0.6), lineWidth: 2)
)
.shadow(color: Color.brandPrimary.opacity(0.3), radius: 8, x: 0, y: 0)
```

### Input Fields

#### Chat Input

```swift
TextEditor(text: $text)
    .font(.system(size: 15))
    .foregroundColor(.white)
    .padding(12)
    .background(
        RoundedRectangle(cornerRadius: 20, style: .continuous)
            .fill(Color.surfaceCard)
    )
    .overlay(
        RoundedRectangle(cornerRadius: 20, style: .continuous)
            .stroke(Color.borderDefault, lineWidth: 1)
    )
```

### Cards

```swift
.background(
    RoundedRectangle(cornerRadius: 16, style: .continuous)
        .fill(Color.surfaceCard)
)
.overlay(
    RoundedRectangle(cornerRadius: 16, style: .continuous)
        .stroke(Color.borderSubtle, lineWidth: 1)
)
.shadow(color: .black.opacity(0.1), radius: 12, x: 0, y: 6)
```

## Animation Specifications

### Durations

```swift
static let durationInstant: Double = 0.1
static let durationFast: Double = 0.2
static let durationNormal: Double = 0.3
static let durationSlow: Double = 0.5
static let durationSlower: Double = 0.8
```

### Curves

```swift
static let curveStandard = Animation.easeInOut(duration: durationNormal)
static let curveEnter = Animation.easeOut(duration: durationNormal)
static let curveExit = Animation.easeIn(duration: durationFast)
static let curveBounce = Animation.spring(response: 0.4, dampingFraction: 0.7)
static let curveSmooth = Animation.interpolatingSpring(stiffness: 300, damping: 30)
```

### Transitions

```swift
// Fade
.transition(.opacity)

// Scale + Fade
.transition(.scale.combined(with: .opacity))

// Slide up
.transition(.move(edge: .bottom).combined(with: .opacity))

// Custom asymmetric
.transition(.asymmetric(
    insertion: .scale.combined(with: .opacity),
    removal: .opacity
))
```

## Implementation

### Create Design System File

Create `/apps/macos/Sources/SOPHIAClaw/DesignSystem.swift`:

```swift
import SwiftUI

enum DesignSystem {
    // Colors
    enum Colors {
        static let brandPrimary = Color(purple: 147/255, green: 51/255, blue: 234/255)
        static let brandAccent = Color(purple: 219/255, green: 39/255, blue: 119/255)
        // ... all other colors
    }

    // Typography
    enum Typography {
        static let hero = Font.system(size: 32, weight: .bold)
        static let h1 = Font.system(size: 24, weight: .bold)
        // ... all other fonts
    }

    // Spacing
    enum Spacing {
        static let xs: CGFloat = 4
        static let s: CGFloat = 8
        static let m: CGFloat = 16
        static let l: CGFloat = 24
        static let xl: CGFloat = 32
    }

    // Animation
    enum Animation {
        static let fast: SwiftUI.Animation = .easeInOut(duration: 0.2)
        static let normal: SwiftUI.Animation = .easeInOut(duration: 0.3)
        static let bounce: SwiftUI.Animation = .spring(response: 0.4, dampingFraction: 0.7)
    }
}

// View Modifiers
extension View {
    func brandPrimaryButton() -> some View {
        self
            .font(.system(size: 14, weight: .semibold))
            .foregroundColor(.white)
            .padding(.horizontal, 16)
            .padding(.vertical, 10)
            .background(
                RoundedRectangle(cornerRadius: 8, style: .continuous)
                    .fill(DesignSystem.Colors.brandPrimary)
            )
    }

    func userBubbleStyle() -> some View {
        self
            .padding(.vertical, 10)
            .padding(.horizontal, 12)
            .background(
                RoundedRectangle(cornerRadius: 18, style: .continuous)
                    .fill(DesignSystem.Colors.brandPrimary.opacity(0.15))
            )
            .overlay(
                RoundedRectangle(cornerRadius: 18, style: .continuous)
                    .stroke(DesignSystem.Colors.brandPrimary.opacity(0.3), lineWidth: 1)
            )
    }

    func assistantBubbleStyle(isActive: Bool = false) -> some View {
        self
            .padding(.vertical, 10)
            .padding(.horizontal, 12)
            .background(
                RoundedRectangle(cornerRadius: 18, style: .continuous)
                    .fill(Color(purple: 35/255, green: 35/255, blue: 45/255))
            )
            .overlay(
                RoundedRectangle(cornerRadius: 18, style: .continuous)
                    .stroke(
                        isActive ? DesignSystem.Colors.brandPrimary.opacity(0.6) : Color.white.opacity(0.08),
                        lineWidth: isActive ? 2 : 1
                    )
            )
            .shadow(
                color: isActive ? DesignSystem.Colors.brandPrimary.opacity(0.3) : .clear,
                radius: 8,
                x: 0,
                y: 0
            )
    }
}
```

### Update ChatMessageViews.swift

Apply the design system to chat bubbles in `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatMessageViews.swift`.

## Quality Checklist

- [ ] All colors use the brand purple/magenta palette
- [ ] No hardcoded colors (use DesignSystem enum)
- [ ] Consistent 8pt spacing throughout
- [ ] All text uses type scale
- [ ] Borders use subtle white opacity
- [ ] Active states have purple glow
- [ ] Animations use standard durations
- [ ] Dark mode optimized
- [ ] Accessibility labels added
- [ ] High contrast tested