Swift Code Style Guidelines

Core Style

• Indentation: 4 spaces
• Braces: Opening brace on same line
• Spacing: Single space around operators and commas
• Naming: PascalCase for types, camelCase for properties/methods

File Organization

• Logical directory grouping
• PascalCase files for types, + for extensions
• Modular design with extensions

Modern Swift Features

• @Observable macro: Replace ObservableObject/@Published
• Swift concurrency: async/await, Task, actor, @MainActor
• Result builders: Declarative APIs
• Property wrappers: Use line breaks for long declarations
• Opaque types: some for protocol returns

Code Structure

• Early returns to reduce nesting
• Guard statements for optional unwrapping
• Single responsibility per type/extension
• Value types over reference types

Error Handling

• Result enum for typed errors
• throws/try for propagation
• Optional chaining with guard let/if let
• Typed error definitions

Architecture

• Avoid using protocol-oriented design unless necessary
• Dependency injection over singletons
• Composition over inheritance
• Factory/Repository patterns

Debug Assertions

• Use assert() for development-time invariant checking
• Use assertionFailure() for unreachable code paths
• Assertions removed in release builds for performance
• Precondition checking with precondition() for fatal errors

Memory Management

• weak references for cycles
• unowned when guaranteed non-nil
• Capture lists in closures
• deinit for cleanup

Overview

ColorfulX is a Metal-backed gradient renderer for Apple platforms that combines LAB color interpolation, spring-based animation, and a configurable compute pipeline to produce vivid multicolor backgrounds. It supports SwiftUI, UIKit, and AppKit with both animated and static gradient rendering.

Architecture

Core Components

Main Classes:

• ColorfulView (Sources/ColorfulX/ColorfulView.swift:11) - SwiftUI wrapper for animated gradients
• AnimatedMulticolorGradientView (Sources/ColorfulX/AnimatedMulticolorGradientView.swift:22) - Core animated gradient view with Metal rendering
• MulticolorGradientView (Sources/ColorfulX/MulticolorGradientView.swift:17) - Base Metal-backed gradient view
• MetalLink (Sources/ColorfulX/MetalLink.swift:15) - Metal rendering abstraction
• MetalProgram (Sources/ColorfulX/MetalProgram.swift:14) - Metal shader program management

Animation System:

• SpeckleAnimationDirector (Sources/ColorfulX/SpeckleAnimationDirector.swift:8) - Abstract animation director protocol
• SpeckleAnimationRandomDirector (Sources/ColorfulX/SpeckleAnimationRandomDirector.swift:8) - Default random animation director
• animationDirector property in AnimatedMulticolorGradientView (Sources/ColorfulX/AnimatedMulticolorGradientView.swift:35) - Immutable animation behavior set at initialization

Color System:

• ColorfulPreset (Sources/ColorfulX/ColorfulPreset.swift:10) - Built-in color presets
• ColorfulColors (Sources/ColorfulX/ColorfulColors.swift:8) - Protocol for custom palettes
• Uses ColorVector dependency for LAB color interpolation

Platform Support:

• MetalView+UIKit.swift (Sources/ColorfulX/MetalView+UIKit.swift:9) - UIKit extensions
• MetalView+AppKit.swift (Sources/ColorfulX/MetalView+AppKit.swift:9) - AppKit extensions
• SwiftUI integration via ColorfulView and MulticolorGradient

Build & Development

Prerequisites

• Swift 5.9+
• Xcode 15+
• Apple platforms: iOS 13+, macOS 11+, macCatalyst 13+, tvOS 13+, visionOS 1+
• Metal support required

Building

./Scripts/test.build.sh

Key Parameters

Animated Views:

• speed - Animation speed factor
• bias - Gradient spread control (0.00001-0.01 typical)
• noise - Procedural noise amount
• transitionSpeed - Color transition speed
• frameLimit - FPS cap (0=unlimited)
• renderScale - Resolution scaling for performance

Static Views:

• power - Falloff curve shaping
• bias - Gradient spread control

Development Workflow

1. Make changes to Sources/ColorfulX/
2. Test with Example app (Example/Workspace.xcworkspace)
3. Run ./Scripts/test.build.sh to verify builds for all platforms
4. Commit changes

File Organization

Sources/ColorfulX/
├── AnimatedMulticolorGradientView*.swift - Animated gradient core
├── ColorfulView.swift - SwiftUI integration
├── ColorfulPreset.swift - Color presets
├── ColorfulColors.swift - Color palette protocol
├── Metal*.swift - Metal rendering
├── MulticolorGradientView*.swift - Static gradients
└── Various extensions and utilities

Performance Tips

• Use lower frameLimit or renderScale on battery-constrained devices
• Keep colors ≤ 8 to avoid truncation
• Set speed = 0 for frozen animation instead of static view
• Lower noise for better performance