# Vibes iOS Design System Rules for Figma Integration

## Overview

This document provides comprehensive rules for converting Figma designs to SwiftUI components in the Vibes iOS application using Model Context Protocol (MCP). The project follows a design-focused development approach with strong integration between Figma and SwiftUI.

---

## 1. Token Definitions

### Location and Structure
- **Primary Token File**: `/vibes/Constants.swift:10-312`
- **Format**: Nested Swift structs with static color and typography definitions
- **Architecture**: Semantic tokens (foreground, background, accent) + raw palette values

### Color Token Structure
```swift
// Semantic Colors - Use these in components
Constants.Colors.Background.primary     // #101012 (dark)
Constants.Colors.Background.secondary   // #1c1c1f (lighter dark)
Constants.Colors.Background.tertiary    // #252529 (even lighter)
Constants.Colors.Foreground.primary     // #f7f4ef (light text)
Constants.Colors.Foreground.secondary   // #c2c2c1 (secondary text)

// Raw Palette - For reference/advanced usage
Constants.Palette.Dumbo._50 to _950     // Gray scale
Constants.Palette.Strawberry._100 to _900 // Brand pink
```

### Typography Token Structure
```swift
Constants.Typography.largeTitle         // 18pt PP Neue Montreal Medium
Constants.Typography.largeRegular       // 18pt PP Neue Montreal Regular  
Constants.Typography.mediumTitle        // 16pt PP Neue Montreal Medium
Constants.Typography.mediumRegular      // 16pt PP Neue Montreal Regular
Constants.Typography.smallTitle         // 14pt PP Neue Montreal Medium
```

### Mapping Figma to SwiftUI Tokens
- **Foreground/Primary** → `Constants.Colors.Foreground.primary` 
- **Background/Secondary** → `Constants.Colors.Background.secondary`
- **Large - Title** → `Constants.Typography.largeTitle` + `.tracking(0.36)`
- **Medium** → `Constants.Typography.mediumRegular` + `.tracking(0.32)`

---

## 2. Component Library Architecture

### Component Hierarchy
```
/vibes/Components/
├── LargeButton.swift        // 56pt height, primary actions
├── MediumButton.swift       // 40pt height, secondary actions  
├── SmallButton.swift        // 32pt height, tertiary actions
├── CustomAlert.swift        // Modal dialogs
├── CustomSheet.swift        // Bottom sheets
├── Player/                  // Media player components
├── Forms/                   // Input components
└── Navigation/              // Navigation components
```

### Component Pattern
All button components follow this structure:
```swift
struct ComponentName: View {
    // Properties
    let title: String?
    let iconAssetName: String?
    let variant: ComponentVariant
    let action: () -> Void
    
    // Variant-based styling
    enum ComponentVariant {
        case primary, secondary, tertiary
        
        var backgroundColor: Color { /* variant logic */ }
        var textColor: Color { /* variant logic */ }
    }
    
    // Convenience initializers
    static func secondary(_ title: String, action: @escaping () -> Void) -> Self
}
```

### Button Sizing Standards
- **LargeButton**: 56pt height, 24pt horizontal padding, 100pt corner radius
- **MediumButton**: 40pt height, 16pt horizontal padding, 100pt corner radius  
- **SmallButton**: 32pt height, 16pt horizontal padding, 100pt corner radius
- **Icon-only variants**: Square (56x56, 40x40, 32x32)

---

## 3. Asset Management

### Icon System
- **Location**: `/vibes/Assets.xcassets/Icon/`
- **Format**: PDF vector files with `Contents.json` metadata
- **Naming Convention**: `Icon/kebab-case-name` (e.g., `Icon/arrow-right`, `Icon/music-note`)
- **Usage**: `Image("Icon/create")` with `.renderingMode(.template)` for tinting

### Icon Categories
- **Navigation**: `arrow-left`, `arrow-right`, `chevron-down`, `close`
- **Actions**: `create`, `edit`, `play`, `pause`, `download`
- **Content**: `music-note`, `image`, `video`, `microphone`
- **Interface**: `gear`, `filter`, `search`, `more-horizontal`

### Other Asset Types
- **Artwork**: `/Assets.xcassets/Artwork/` - Numbered image sets (1-13)
- **Avatars**: `/Assets.xcassets/Avatar/` - User profile images (1-10)
- **Video Assets**: `.dataset` bundles for media files
- **Special Images**: `aura.imageset` for special button backgrounds

### Asset Resolution Strategy
1. Search existing icons in `/Icon/` folder first
2. Use closest semantic match if exact icon doesn't exist
3. For missing assets, use placeholders from existing categories
4. Never reference non-existent assets

---

## 4. Typography and Spacing

### Font System
- **Primary Font**: PP Neue Montreal (Medium/Regular weights)
- **Monospace Font**: Input Sans (for timecodes/technical text)
- **Location**: `/vibes/fonts/` directory with `.otf` and `.ttf` files

### Text Styling Pattern
```swift
Text("Title")
    .font(Constants.Typography.largeTitle)
    .foregroundColor(Constants.Colors.Foreground.primary)
    .tracking(0.36)  // Letter spacing from Figma
    .multilineTextAlignment(.center)
```

### Standard Spacing Values
- **Component Padding**: 32pt (alert containers), 24pt (buttons), 16pt (small elements)
- **Element Spacing**: 32pt (major sections), 8pt (related elements), 4pt (tight groupings)
- **Corner Radius**: 24pt (alerts/sheets), 100pt (buttons - fully rounded)

---

## 5. SwiftUI Implementation Patterns

### Layout Structure
```swift
VStack(spacing: 32) {
    // Title/content section
    VStack(spacing: 8) {
        Text(title).font(Constants.Typography.largeTitle)
        Text(message).font(Constants.Typography.mediumRegular)
    }
    
    // Action section  
    HStack(spacing: 8) {
        LargeButton.secondary("Cancel", action: cancelAction)
        LargeButton(title: "Confirm", variant: .primary, action: confirmAction)
    }
}
.padding(32)
.background(Constants.Colors.Background.secondary)
.clipShape(RoundedRectangle(cornerRadius: 24))
```

### Color Application
- Always use semantic color tokens, not raw hex values
- Apply `.renderingMode(.template)` to icons for proper tinting
- Use `.foregroundColor()` for icon/text tinting
- Use `.background()` for container backgrounds

### Animation Standards
- Use `.easeInOut(duration: 0.2)` for standard transitions
- Apply `.scaleEffect()` and `.opacity()` for button press feedback
- Implement `.transition(.opacity.combined(with: .scale()))` for modal presentations

---

## 6. Figma to SwiftUI Conversion Workflow

### Step 1: Design Analysis
1. Use MCP `get_code` to extract component structure and measurements
2. Use MCP `get_variable_defs` to identify design tokens
3. Use MCP `get_image` to capture visual reference

### Step 2: Token Mapping
1. Map Figma color variables to `Constants.Colors` tokens
2. Map typography specs to `Constants.Typography` + tracking values
3. Extract spacing, corner radius, and sizing specifications

### Step 3: Component Structure
1. Identify reusable vs. one-off components
2. Choose appropriate base component (LargeButton, CustomAlert, etc.)
3. Implement using established patterns and conventions

### Step 4: Asset Integration
1. Reference existing icons from `/Icon/` directory
2. Use semantic naming that matches design intent
3. Apply consistent rendering modes and tinting

### Step 5: Layout Implementation  
1. Use `VStack`/`HStack` with proper spacing values
2. Apply padding using standard increments (8, 16, 24, 32pt)
3. Implement responsive behavior with `frame()` modifiers

---

## 7. Quality Standards

### Code Requirements
- ✅ Use existing design tokens from `Constants.swift`
- ✅ Reference real assets from asset catalog
- ✅ Follow established component patterns
- ✅ Include proper accessibility support
- ✅ Implement consistent animation timing
- ✅ Use semantic color/typography tokens
- ✅ Apply proper corner radius and spacing values

### Design Fidelity Checklist
- ✅ Exact spacing matches Figma measurements
- ✅ Typography sizing and tracking applied correctly
- ✅ Color values mapped to semantic tokens
- ✅ Corner radius and padding values match design
- ✅ Component hierarchy and structure preserved
- ✅ Interactive states properly implemented

---

## 8. Project Integration

### File Structure
- **New Components**: Place in `/vibes/Components/` with descriptive names
- **Views**: Screen-level components go in `/vibes/Views/`
- **Utilities**: Extensions and modifiers in appropriate subdirectories

### Naming Conventions
- **Components**: PascalCase (e.g., `CustomAlert`, `LargeButton`)
- **Files**: Match component name + `.swift` extension
- **Assets**: kebab-case with semantic prefixes (`Icon/`, `Avatar/`)

### Integration Pattern
1. Create component following established patterns
2. Add convenience initializers for common use cases
3. Include `#Preview` with realistic examples
4. Test with existing design tokens and assets
5. Ensure responsive behavior across device sizes

This comprehensive guide ensures consistent, high-quality conversion of Figma designs to SwiftUI components while maintaining the established design system patterns and technical architecture of the Vibes iOS application.